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Foreword 



rd , 



This Technical Specification has been produced by the 3 Generation Partnership Project (3 GPP). 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 
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Scope 



A Subscriber Identity Module Application Programming Interface (SIM API) has been defined in TS 42.019 [4] as a 
technology-independent API by which toolkit applications and (U)SIMs co-operate. That specification is independent 
of the programming language technology used to create the application, the platform used to host the application and 
the runtime environment used to execute the application. 

The present document includes information applicable to (U)SIM toolkit application developers creating applications 
using the C programming language ISO/IEC 9899 [7]. The present document describes an interface between toolkit 
applications written in the C programming language and the (U)SIM in order to realize the co-operation set forth in 
TS 42.019 [4]. In particular, the API described herein provides the service of assembling proactive commands and 
disassembling the responses to these commands for the application programmer. 

Software tools, integrated software development environments and software management systems that may be used to 
create application programs are explicitly out of scope of the present document. 
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3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the following terms and definitions apply: 

application: computer program that defines and implements a useful domain-specific functionality 

The term may apply to the functionality itself, to the representation of the functionality in a programming language, or 

to the realization of the functionality as executable code. 

application executable: representation of an application as collection of executable codes 

application program: representation of an application in a programming language such as assembly language, C, Java, 
WML or XHTML 

Application Programming Interface (API): collection of entry points and data structures that an application program 
can access when translated into an application executable 

byte code: processor-independent representation of a basic computer operation such as "increment by one" that is 
executed by computer program called a byte code interpreter 

data structure: memory address that can be accessed by an application executable in order to read or write data 

entry point: memory address that can be branched to by an application executable in order to access functionality 

defined by an application-programming interface 

Depending on the software technology, an entry point is also called a subroutine, a function or a method. 

executable code: generic term for either byte code or native code 

framework: defines a set of Application Programming Interface (API) functions for developing applications and for 
providing system services to those applications 

loadfile: representation of an application executable that is transmitted from the terminal to the smart card operating 

system 

A loadfile typically includes information about the application executable in addition to the application executable 

itself. 

native code: processor-dependent representation of a basic computer operation such as "increment by one" that is 
executed by the hardware circuitry of a computer's central processing unit 

toolkit application: uses the commands described in TS 3 LI 11 and TS 11.14 

3.2 Abbreviations 

For the purpose of the present document, the following abbreviations apply: 

APDU Application Protocol Data Unit 

API Application Programming Interface 

CAT Card Application Toolkit 

CS Circuit Switched 

DCS Digital Cellular System 

DF Dedicated File 

DTMF Dual Tone Multiple Frequency 

EF Elementary File 

ELF Executable and Linkable Format 

FID File Identifier 

GSM Global System for Mobile communications 

ME Mobile Equipment 

NAA Network Access AppHcation (SIM or USIM) 

OTA Over The Air 

SIM Subscriber Identity Module 
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SMS 

STK 

SW 

TAR 

TLV 

TPDU 

UICC 

URL 

USIM 

USSD 



Short Message Service 

SIM ToolKit 

Status Word 

Toolkit Application Reference 

Tag, Length, Value 

Transport Protocol Data Unit 

(not an acronym) 

Uniform Resource Locator 

Universal Subscriber Identity Module 

Unstructured Supplementary Services Data 



Description 



The (U)SIM Application consists of the following: 

APDU handlers for communicating with the ME; 

- File system and file access control; 

- Toolkit Framework that provides services to Toolkit applications. 

The present document describes the C programming language binding for the interface between the (U)SIM application 
and toolkit applications described in TS 42.019 [4]. This API allows application programmers using the C programming 
language to access functions and data described in TS 3L111 [2] and TS 1L14 [8], such that the (U)SIM-based 
applications and the services they implement can be developed and loaded onto ICCs. If required and supported by the 
underlying smart card technology, toolkit applications can be loaded or deleted remotely, after the card has been issued. 



4.1 



Overview 



The 'C -binding for (U)SIMAPI shall provide function calls for pro-active functions and transport functions. The figure 
below shows the interactions between a typical toolkit application (shown in blue) and the various functional blocks of 
the (U)SIM (shown in orange). The C-bindings for these APIs are presented in subclause 4.2. 
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4.2 Design Rationale and Upward Compatibility 

Some functions on the C SIM API take parameters that correspond to optional TLVs in TS 31.111 [2] and TS 11.14 [8]. 
If the actual parameter value passed to the function is NULL, the corresponding TLV is not passed to the ME; an 
example of an optional parameter is Catlconldentifier that corresponds to the ICON IDENTIFIER TLV. 

Some proactive commands have a very large number of optional TLVs, such as SETUP CALL. Therefore, this API 
offers two variants that address this aspect, CatSetupCall and CatSetupCallEx. The first function, CatSetupCall, takes 
as parameters everything that is necessary to issue a successful SETUP CALL proactive command (i.e. everything 
required to construct the mandatory TLVs as required by TS 31.111 [2] and TS 11.14 [8]) and also includes optional 
user interface TLVs (title and icon) for ease of use. 

The second function, CatSetupCallEx, takes a parameter block that can be extended in future versions of the present 
specification. The parameter block contains members that correspond to all mandatory and optional TLVs for the 
SETUP CALL proactive command. 

The reason for introducing the " . . .Ex" variants is threefold: 

- Rather than extend the parameter list of a function to take a large number of optional parameters for each call, it 
is preferable to set up the parameters using named structure members before issuing the call to the function. 

- If a future version of TS 3 1 . 1 1 1 [2] or TS 1 1 . 14 [8] extends the optional parameters for a proactive command, 
the corresponding parameter block can be extended to encompass these parameters without changing the 
function prototype. 

- Any source code written for an older version of this C SIM API can be recompiled with a later version without 
change and will remain upwardly compatible at the source as long as the suggested coding standards are adhered 
to. 



4.3 Application Triggering 



The application-triggering portion of the SIM Toolkit Framework is responsible for the activation of toolkit 
applications, based on the APDU received by the card. 

The ME shall not be adversely affected by the presence of applications on the (U)ICC card. For instance a syntactically 
correct Envelope shall not result in an error status word in case of a failure of an application. The only application as 
seen by the ME is the (U)SIM application. As a result, a toolkit application may return an error, but this error will not 
be sent to the ME. 

The difference between an application and a toolkit application is that a toolkit application does not typically handle 
APDUs directly. It will handle higher-level messages. Furthermore the execution of a function could span over multiple 
APDUs, in particular, the proactive protocol commands. 

All the applications that have registered interest in the event are triggered in order of their priority. 

- The current context is switched to the toolkit application. 

- A pending transaction is aborted. 

The current file context of the toolkit application is the MF. 

- The current file context of the current selected application is unchanged. 
On termination of a toolkit application execution of CatExit(): 

- The context switches back to the context of the current selected application, the NAA application. 

- A pending toolkit application transaction is aborted. 
Here after are the events that can trigger a toolkit application: 
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EVENT_PROFILE_DOWNLOAD 

Upon reception of the Terminal Profile command by the (U)SIM, the Toolkit Framework stores the ME profile and then 
triggers the registered toolkit application that may want to change their registry. A toolkit application may not be able to 
issue a proactive command. 

EVENT_MENU_SELECTION,EVENT_MENU_SELECTION_HELP_REQUEST 

A toolkit application might be activated upon selection in the ME's menu by the user, or request help on this specific 
menu. 

In order to allow the user to choose in a menu, the Toolkit Framework shall have previously issued a SET UP MENU 
proactive command. When a toolkit application changes a menu entry of its registry object, the Toolkit Framework shall 
dynamically update the menu stored in the ME during the current card session. The SIM Toolkit Framework shall use 
the data of the EFsume file (TS 51.011 [11] and TS 31.102 [15]) when issuing the SET UP MENU proactive command. 

The positions of the toolkit application menu entries in the item list, the requested item identifiers and the associated 
limits (e.g. maximum length of item text string) are defined at the loading of the toolkit application. 

If at least one toolkit application registers to EVENT_MENU_SELECTION_HELP_REQUEST, the SET UP MENU 
proactive command sent by the Toolkit Framework shall indicate to the ME that help information is available. A toolkit 
application registered for one or more menu entries may be triggered by the event 

EVENT_MENU_SELECTION_HELP_REQUEST, even if it is not registered to this event. A toolkit appHcation 
registered for one or more menu entries should provide help information. 

EVENT_FORMATTED_SMS_PP_ENV,EVENT_UNFORMATTED_SMS_PP_ENV, 

EVENT_FORMATTED_SMS_PP_UPD,EVENT_UNFORMATTED_SMS_PP_UPD 

A toolkit application can be activated upon the reception of a short message. There are two ways for a card to receive an 
SMS: via the Envelope SMS-PP Data Download or the UpdateRecord EFsms instruction. 

The reception of the SMS by the toolkit application cannot be guaranteed for the Update Record EFsms instruction. 

The received SMS may be: 

- formatted according to TS 23.048 [3] or an other protocol to identify explicitly the toolkit application for which 
the message is sent; 

- unformatted or using a toolkit application specific protocol the Toolkit Framework will pass this data to all 
registered toolkit applications. 

EVENT_FORMATTED_SMS_PP_ENV 

This event is triggered by an envelope APDU containing an SMS_DATADOWNLOAD BER TLV with an 
SMS_TPDU simple TLV according to TS 23.048 [3]. 

The Toolkit Framework shall: 

- verify the TS 23.048 [3] security of the SMS TPDU; 

- trigger the toolkit application registered with the corresponding TAR defined at application loading; 

- take the optional Application Data posted by the triggered toolkit application if present; 

- secure and send the response packet. 

The toolkit application will only be triggered if the TAR is known and the security verified. Application data will also 
be deciphered. 

EVENT_UNFORMATTED_SMS_PP_ENV 

The registered toolkit applications will be triggered by this event and get the data transmitted in the APDU envelope 
SMS DATADOWNLOAD. 
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EVENT_FORMATTED_SMS_PP_UPD 

This event is triggered by Update Record EFsms with an SMS TP-UD field formatted according to TS 23.048 [3]. 

The Toolkit Framework shall: 

- update the EFsms file with the data received, it is then up to the receiving toolkit application to change the SMS 
stored in the file (i.e. the toolkit application need to have access to the EFsms file); 

- verify the TS 23.048 [3] security of the SMS TPDU; 

- convert the Update Record EFsms in a TLV List, an EnvelopeHandler; 

- trigger the toolkit application registered with the corresponding TAR defined at application loading. 

EVENT_UNFORMATTED_SMS_PP_UPD 

The SIM Toolkit Framework will first update the EFsms file, convert the received APDU as described above, and then 
trigger all the registered toolkit applications. All of them may modify the content of EFsms (i.e. the toolkit applications 
need to have access to the EFsms file). 

EVENT_UNFORMATTED_SMS_CB 

When the ME receives a new cell broadcast message, the cell broadcast page may be passed to the card using the 
envelope command, e.g. the application may then read the message and extract a meaningful piece of information that 
could be displayed to the user, for instance. 

EVENT_CALL_CONTROL_BY_SIM 

When the NAA is in call control mode and when the user dials a number, this number is passed to the Toolkit 
Framework. Only one toolkit application can handle the answer to this command: call barred, modified or accepted. 

EVENT_EVENT_DOWNLOAD_MT_CALL,EVENT_EVENT_DOWNLOAD_CALL_CONNECTED, 

EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED,EVENT_EVENT_DOWNLOAD_LOCATION_STATUS, 

EVENT_EVENT_DOWNLOAD_USER_ACTIVITY,EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE, 

EVENT _EVENT_DOWNLO AD _CARD_READER_STATUS 

The toolkit application will be triggered by the registered event download trigger, upon reception of the corresponding 
Envelope command. In order to allow the toolkit application to be triggered by these events, the Toolkit Framework 
shall have previously issued a SET UP EVENT LIST proactive command. When a toolkit application changes one or 
more of these requested events of its registry, the Toolkit Framework shall dynamically update the event list stored in 
the ME during the current card session. 

EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM 

Before sending an SMS MO entered by the user, the SMS is submitted to the Toolkit framework. Only one toolkit 
application can register to this event. 

EVENT _TIMER_EXPIRATION 

This event is registered when the application executes a successful Toolkit CatGetTimer(). The toolkit application can 
then manage this (these) timer(s), and it will be triggered at the reception of the APDU Envelope TIMER 
EXPIRATION. The Toolkit Framework shall reply busy to this Envelope APDU if it cannot guaranty to trigger the 
corresponding toolkit application. 

EVENT _UNRECOGNIZED_ENVELOPE 

The application registered to this event shall be triggered by the framework if the BER-TLV tag contained in the 
ENVELOPE APDU is not defined in the associated release of TS 31.111 [2] and TS 11.14 [8] and if no corresponding 
constant is defined in the list of the ToolkitConstants interface. By providing the means to transfer an arbitrary block of 
data, the Unrecognized Envelope Event will allow a toolkit application to handle the evolution of the specifications 
TS 31.111 [2]andTS 11.14 [8]. 
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EVENT_STATUS_COMMAND 

At reception of a STATUS APDU command, the SIM Toolkit Framework shall trigger the registered toolkit 
application. 

A range of events is reserved for experimental and proprietary usage (from -128 to -1). As the definition of these events 
is not standardized, the use of these events may make the toolkit application behave differently on different platforms. 

The toolkit application shall be triggered for the registered events upon reception, and shall be able to access to the data 
associated to the event using OpenEnvelope() or the low-level functions. 

The order of triggering the toolkit application shall follow the priority level of each toolkit application defined at its 
loading. If several toolkit applications have the same priority level, the last loaded toolkit application takes precedence. 

4.4 Proactive command handling 

The (U)SIM application toolkit protocol (i.e. 91xx, Fetch, Terminal Response) is handled by the network access 
application and the Toolkit Framework. The toolkit application shall not handle those events. 

The network access application and the Toolkit Framework shall handle the transmission of the proactive command to 
the ME, and the reception of the response. The Toolkit Framework will then return in the toolkit application just after 
the proactive command. It shall then provide to the toolkit application the values as indicated in the function 
parameters. It also provides the raw return information so that the toolkit application can analyse the response. 

The proactive command is sent to the ME as defined and constructed by the toolkit library without any check of the 
Toolkit Framework. 

The toolkit application shall not issue the following proactive commands: SET UP MENU, SET UP EVENT LIST, 
POLL INTERVAL, POLLING OFF; as those are system proactive commands that will affect the services of the Toolkit 
Framework. 

4.5 Application Loading 

Applications compliant to the present document are represented for loading as loadfiles in the Executable and Linkable 
Format (ELF) described in Tool Interface Standard (TIS) Executable and Linking Format Specification [9] and 
SYSTEM V Application Binary Interface [10]. The application executable in the ELF loadfile may be either native 
code or byte code that has been created through a process of compiling the representation of the application program in 
the C programming language. 

The e_machine entry in the ELF header is set to according to the table in annex A and indicates the architecture for 
which the application executable in the loadfile has been prepared. 

Coding for other processors, processor instruction set extensions and byte code interpreters will be defined as needed 
processor-specific or interpreter- specific supplements to SYSTEM V Application Binary Interface [10] may also be 
provided as needed. 

Loadfile linkers, loaders and installers, whether on-card or off-card, return an error condition if the application 
representation in the loadfile cannot be accommodated or if resources requested by the application are not available. 

The over-the-air application loading mechanism, protocol and application life cycle are defined in TS 23.028 [3]. 



5 'C'-language binding for (U)SIM API 

5.1 Overview 

This subclause presents the 'C'-language binding to (U)SIM API. It is divided into sections as follows: 
- Toolkit application entry and exit. 
Man-Machine Interface. 
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- Timers. 

- Supplementary card reader. 

- UICC file store access. 

- Registry. 

- Miscellaneous. 
Low-level functions. 
Network services. 

- Supporting data types. 

For each function, the prototype is given followed by a table describing the parameters and whether they are input [in] 
or output [out] parameters. There is explanatory text which explains the function's purpose and whether it is a proactive 
command or not. 



5.2 Toolkit Application Functions 



Toolkit applications will start by executing the application-defined function main. There are no arguments to main, nor 
are there any return results. The application can find out why it was invoked using the CatGetFrameworkEventt 
function. The Framework events that can cause an application to be invoked can be split into the following groups: 

Command monitoring. 

- ME monitor events. 

- Application lifecycle change. 

Command monitoring enables applications to be invoked when the framework receives commands from the ME. 
Currently supported commands that can be monitored are: 

- TERMINAL PROFILE: monitoring this command enables an application to be invoked when the ME is 
powered on. 

- STATUS: monitoring this command enables an application to be invoked when the ME polls for proactive 
commands. 

- ENVELOPE: monitoring this command enables the application to be informed of specific envelope type arrival 
for example call control envelopes can be monitored. 

ME monitor events are events that the framework can ask the ME to monitor; for example an event can be sent on call 
connection. ME monitored events are delivered to the application in the EVENT DOWNLOAD envelope as received 
from the ME. 

The application lifecycle event enables the framework to invoke an application when the application status has changed. 
This is mainly to enable an application to be run at installation time so that it can set up its registry entries. The details 
of the application lifecycle events are provided in TS 3 LI 16 [14]. 

5.2.1 main 

void 

main (void) ; 

The main function is the application entry point. The application should not return from main\ it must call the CatExit 
function. 

An example main function is given below: 

void main (void) 

{ 

switch (CatGetFrameworkEvent ( ) ) 
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case EVENT_APPLICATION_LIFECYCLE_INSTALL : 

// set up registry for this application 

CatSetMenuString( 

CatNotifyOnEnvelope (SMS_PP_DOWNLOAD_TAG, 1) ; 

CatNotifyOnEvent (CARD_READER_STATUS, 1) ; 

break; 
case EVENT ENVELOPE COMMAND: 



{ 



BYTE length; 

switch (CatOpenEnvelope (&length) ) 

{ 

case MENU_SELECTION_TAG: 

// search for help request 

break; 
case SMS_PP_DOWNLOAD_TAG: 

break; 
case EVENT_DOWNLOAD_TAG : 

// search for card reader status event 

break; 
default: 

CatExit ; 



break; 
default : 
CatExit 
break; 



CatExit ; 



5.2.2 CatGetFrameworkEvent 

CatFrameworkEventType 
CatGetFrameworkEvent (void) ; 



RETURN 



Framework event type that caused the application to run; see 
CatFrameworkEventType for details. 



5.2.3 CatExit 

void 

CatExit (void) ; 



CatExit causes the application to terminate execution and return control to the framework. When the application is 
restarted, it enters at main. 



5.3 Registry 



The menu entry(ies) of the application, together with the set of framework events that the application is interested in, 
may be registered using the functions defined in this subclause. 



5.3.1 CatSetMenuString 



void 

CatSetMenuString (BYTE MenuID, 

BYTE MenuStringLength , const void *MenuString, 

const Catlconldentif ier *IconIdentifier, 

BYTE HelpAvailable, 

BYTE Next Act ion) ; 
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MenulD 


[in] 


Tine menu ID by which this entry is known. 


MenuStringLength 


[in] 


The length, in bytes, of IVIenuString. 

The menu entry to be placed in the registry. If MenuString is NULL or 


MenuString 


[in] 


MenuStringLength is zero, any existing menu entry associated with MenulD 

is removed and is not displayed by the ME. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier is NULL or if Iconldentifier. Uselcon is zero, no icon identifier is 
sent to the ME. 


HelpAvailable 


[in] 


If non zero the application can supply help. 


NextAction 


[in] 


The (optional) next action value 



CatSetMenuString allows the application to define a menu entry together with an icon. A non-zero value can be 
supplied if a next action indicator is required. This function will implicitly request that the application is notified of 
menu selection envelopes i.e. there is no requirement to call the CatNotifiyOnEnv elope function. An application can 
have several menu entries and must examine the menu selection envelope to decide which menu selection caused it to 
be invoked. 

The ordering of menu entries within a menu presented by the ME is based on increasing integer values of identifiers 
selected by the application. Note that any application's menu item ordering may be further overridden by an external 
source, e.g. card issuer, via a request to the SIM Toolkit framework this mechanism is beyond the scope of the present 
document. 

5.3.2 CatNotifyOnFrameworkEvent 

void 

CatNotifyOnFrameworkEvent (CatFrameworkEventType Event, BYTE Enabled); 



c: . r- n A framework event the application is interested in, see 

^' ^ CatFrameworkEventType for details. 

If non-zero the framework event is monitored otherwise the framework event 
isn't monitored. By default only application lifecycle events are monitored. 



Enabled [in] 



CatNotifyOnFrameworkEvent enables the application to add/remove a framework event to/from the set of framework 
events that it is interested in. 



5.3.3 CatNotifyOn Envelope 

void 

CatNotifyOnEnvelope (CatEnvelopeTagType Tag, BYTE Enabled); 



Tag [in] 



The particular envelope type to monitor; see CatEnvelopeTagType for 
details. 



Fnahlpd \'n^ '^ non-zero the envelope type is monitored otherwise the envelope type isn't 

^ ^ monitored. 



CatNotifyOnEnvelope enables the application to add/remove an envelope monitoring event to/from the set of the 
envelope monitoring events it is interested in. Note that the monitoring of MENU SELECTION, TIMER EXPIRATION 
and EVENT DOWNLOAD envelopes is handled by the framework. 

5.3.4 CatNotifyOn Event 

void 

CatNotifyOnEvent (CatEventType EventType, BYTE Enabled); 



EventType [in] The particular event type to monitor; see CatEventType for details. 

Enabled [in] If non-zero the event type is monitored otherwise the event isn't monitored. 



CatNotifyOnEvent enables the application to add/remove an ME monitored event to/from the set of ME monitored 
events it is interested in. 
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5.4 Man-Machine Interface 
5.4.1 CatAddltem 

void 

CatAddltem (BYTE ItemTextLength, const void * ItemText , BYTE Itemldentifier) ; 



ItemTextLength [in] The length in bytes of the following ltemTexti'\e\6. 

ItemText [in] Text associated with item. 

Specifies a unique identifier to be associated with this selection. This value is 
Itemldentifier [in] returned in the Selectedltem parameter of CatSelectltem if this item is 

selected from the menu. 



CatAddltem adds an item to a list for the user to select. See CatSelectltem below for details on the construction of a 
display list. 

5.4.2 CatSelectltem 

void 

CatSelectltem (BYTE TitleLength, const void *Title, 
CatSelectltemOptions Options) ; 



TitleLength [in] The length in bytes of Title. 

Title [in] Title of the list of choices. 

Options [in] Acceptable values for this parameter are listed in CatSelectltemOptions. 



CatSelectltem initiates the construction of a list of items to be displayed to the user and from which the user is expected 
to select exactly one entry. After CatSelectltem has been called, entries are added to the list one at a time using the 
CatAddltem entry point above. When all items have been added to the list, the list is sent to the ME using the 
CatEndSelectltem entry point below. CatEndSelectltem causes the list to be displayed and returns to the caller the item 
selected. 

5.4.3 CatEndSelectltem 

CatGeneralResult 

CatEndSelectltem (BYTE * Selectedltem, 

const Catlconldentif ier * Iconldentifier) ; 



Selectedltem 


[out] 


Iconldentifier 


[in] 


RETURN 





Index of item selected by user. 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier is NULL or if Iconldentifier. Uselcon is zero, no icon identifier is 

sent to the ME. 

The GeneralResult code of the SELECT ITEM proactive command. 



CatEndSelectltem issues the proactive command SELECT ITEM that displays on the ME a list of items for the user to 
choose from. The terminal response is parsed and if successful the Selectedltem parameter is set to the index of the item 
chosen. See CatSelectltem above for details on the construction of a display list. 

5.4.4 CatDisplayText 

CatGeneralResult 

CatDisplayText (CatDCSValue TextDCS , BYTE TextLength, const void *Text, 

CatDisplayTextOptions Text Opt ions, 

CatTextFormat TextFormat, 

CatForegroundColor ForegroundColour , 

CatBackgroundColour BackgroundColour , 

const Catlconldentifier * Iconldentifier, 

BYTE ImmediateResponse) ; 
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TextDCS 


[in] 


TextLength 

Text 

TextOptions 

TextFormat 

ForegroundColour 

BackgroundColour 


[in] 
[in] 
[in] 
[in] 
[in] 
[in] 


Iconldentifier 


[in] 


ImmediateResponse 


[in] 


RETURN 





The data coding scheme for Text. Acceptable values for this parameter are 

listed in CatPCSValue . 

The length in bytes of Text. 

String to display on ME. 

Acceptable values for this parameter are listed in CatPisplavTextOptions . 

Format of text; e.g. bold, italic, etc. 

Foreground colour of text; i.e. colour of the letters. 

Background colour of text; i.e. colour filled in behind the letters. 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier \s NULL or if Iconldentifier.Uselcon is zero, no icon identifier 

is sent to the ME. 

True-program continues execution as soon as ME receives instruction. 

False-program waits until text is cleared on the ME before continuing, and 

the Immediate Response TLV is not passed to the ME. 

The GeneralResult code of the DISPLAY TEXT proactive command. 



5.4.5 CatGetlnKey 



CatGeneralResult 

CatGetlnKey (CatDCSValue TitleDCS, BYTE TitleLength, const void * Title, 

CatGetlnKeyOptions Options, 

const Catlconldentifier * Iconldentifier , 

CatDCSValue *DCSOut, void *KeyOut) ; 



TitleDCS 


[in] 


The data-coding scheme for Title. Acceptable values for this parameter are 
listed in CatDCSValue. 


TitleLength 

Title 

Options 


[in] 
[in] 
[in] 


The length in bytes of Title. 

String to display on ME. 

Acceptable values for this parameter are listed in CatGetlnKevOotions. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Icon Identifier \s NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 
sent to the ME. 


DcsOut 


[out] 


The packing type of the returned key. This parameter is set to one of the 
values listed in CatDCSValue. 


KeyOut 
RETURN 


[out] 


The key pressed. 

The GeneralResult code of the GET INKEY proactive command. 



CatGetlnKey issues the proactive command GET INKEY. The terminal response is parsed and if successful the 
DCSOut and KeyOut parameters are updated. 



5.4.6 CatGetlnput 



CatGeneralResult 

CatGetlnput (CatDCSValue TitleDCS, BYTE TitleLength, const void *Title, 
CatGetlnputOptions Options, 

CatDCSValue DefaultReplyDCS, 

BYTE DefaultReplyLength, const void *DefaultReply, 

BYTE MinimumResponseLength, 

BYTE MaximumResponseLength, 

const Catlconldentifier * Iconldentifier, 

CatDCSValue *MsgOutDCS, BYTE *MsgOutLength, void *MsgOut) ; 
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TitleDCS 


[in] 


TitleLength 

Title 

Options 


[in] 
[in] 
[in] 


DefaultReplyDCS 


[in] 


DefaultReplyLength 


[in] 


DefaultReply 


[in] 


MinimumResponseLength 
MaximumResponseLength 


[in] 
[in] 


Icon Identifier 


[in] 


MsgOutDCS 


[out] 


MsgOutLength 

MsgOut 

RETURN 


[out] 
[out] 



The data-coding scheme for Title. Acceptable values for this parameter are 

listed in CatPCSVaiue . 

The length in bytes of Title. 

String to display on ME while waiting for the user to press a key. 

Acceptable values for this parameter are listed in CatGetlnputOptions . 

The data-coding scheme for DefaultReply. Acceptable values for this 

parameter are listed in CatPCSVaiue . 

The length in bytes of DefaultReply. 

Default response string; use NULL for "no reply"-no Default Reply tag 

length value (TLV) is sent to the ME. 

Minimum allowed length for the response, in either characters or digits. 

Maximum allowed length for the response, in either characters or digits. 

Optional icon identifier; see Catlconldentifier for member details. If 

Icon Identifier \s NULL or if Iconldentifier.Uselcon is zero, no icon identifier 

is sent to the ME. 

Packing type of the returned data. This parameter is set to one of the 

values listed in CatPCSVaiue . 

Length of the returned message in bytes. 

A pointer to where the returned string or message is placed. 

The GeneralResult code of the GET INPUT proactive command. 



CatGetlnput issues the proactive command GET INPUT. The terminal response is parsed and if successful 
MsgOutDCS, MsgOutLength, MsgOut parameters are updated. 

5.4.7 CatSetupldleModeText 

CatGeneralResult 

CatSetupldleModeText (CatDCSValue TextDCS , BYTE TextLength, const void *Text, 
const Catlconldentifier * Iconldentifier) ; 



TextDCS 


[in] 


The data-coding scheme for Text. Acceptable values for this parameter are 
listed in CatDCSValue. 


TextLength 


[in] 


The length in bytes of Text. 


Text 


[in] 


String to display while ME is idle. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier '\s NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 
sent to the ME. 


RETURN 




The GeneralResult code of the SETUP IDLE MODE TEXT proactive 
command. 



CatSetupldleModeText issues the proactive command SET UP IDLE MODE TEXT that sets the ME's default text 
string. 



5.4.8 CatPlayTone 



CatGeneralResult 

CatPlayTone (BYTE TextLength, const void *Text, 
CatTone Tone, 

CatTimeUnit Units, BYTE Duration, 
const Catlconldentifier * Iconldentifier) 



TextLength 
Text 

Tone 

Units 
Duration 

Iconldentifier 

RETURN 



[in] 
[in] 

[in] 

[in] 
[in] 

[in] 



The length in bytes of the string TextXo display on the ME. 

String to display on ME while sound is being played. 

Specifies tone to play. Acceptable values for this parameter are listed in 

CatTone . 

Unit of time specified for duration parameter. Acceptable values for this 

parameter are listed in CatTimeUnit . 

Amount of time to play the tone, in units specified in the Units parameter 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier \s NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 

sent to the ME. 

The GeneralResult code of the PLAY TONE proactive command. 
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CatPlayTone issues the proactive command PLAY TONE. 

5.5 Timers 

5.5.1 CatGetTimer 

BYTE 

CatGetTimer (void) ; 

I RETURN The identifier of the timer. | 

CatGetTimer returns the ID of a timer that is not currently in use. If no timer is available, this function returns zero. 
Timer identifiers are assigned by the framework. 

5.5.2 CatFreeTimer 

void 

CatFreeTimer (BYTE TimerlD) ; 



TimerlD [in] ID of timer to free; obtained from CatGetTimer. 



CatFreeTimer frees the handle to the specified timer, making it available for the next request. It is not a proactive 
command. No information is passed to the ME by this function. 

5.5.3 CatStartTimer 

void 

CatStartTimer (BYTE TimerlD, CatTimerValue *TimerValue) ; 



TimerlD [in] ID of the timer to initialize; obtained from CatGetTimer . 

-r. ,, , r. , Initial value of the timer. The value is specified in a structure of type 

T,merValue [m] CatTimerValue . 

RETURN The GeneralResult code of the TIMER MANAGEMENT proactive command. 



CatStartTimer issues a proactive TIMER MANAGEMENT command to initialize a timer to the parameter values. 

5.5.4 CatGetTimerValue 

void 

CatGetTimerValue (BYTE TimerlD, CatTimerValue *TimerValue) ; 



TimerlD [in] ID of the timer from which to obtain values; obtained from CatGetTimer 

_^. ,, , , ,, The time remaining to run of timer TimerlD. The value is returned in a 

T.merValue [out] ^^^^^^^^^ ^^ ^^^^ CatTimerValue . 

RETURN The GeneralResult code of the TIMER MANAGEMENT proactive command. 



CatGetTimerValue issues a proactive TIMER MANAGEMENT command to obtain the timer's current value. 

5.6 Supplementary Card Reader Management 

These functions access the supplementary card-reader on a dual-slot ME. 
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5.6.1 CatPowerOnCard 

CatGeneralResult 

CatPowerOnCard (CatDevice DevicelD, BYTE *ATRLength, void *ATR) ; 



DevicelD 


[in] 


ATRLength 


[in/out] 


ATR 


[out] 


RETURN 





The device to power on. An acceptable value for this parameter is a card 

reader device selected from CatDevice . 

Size of the ATR buffer on input and the umber of bytes returned by the card 

as the ATR on output. 

Pointer to where answer to reset (ATR) will be stored. 

The GeneralResult code of the POWER ON CARD proactive command. 



CatPowerOnCard issues the proactive command POWER ON CARD that powers on a supplementary card reader. The 
terminal response is parsed and if successful the ATR and ATRLength parameters are. 

5.6.2 CatPowerOffCard 

CatGeneralResult 

CatPowerOffCard (CatDevice DevicelD) ; 



ri ■ iri ri The device to power off. An acceptable value for this parameter is a card 

^' ^ reader device selected from CatDevice . 

RETURN The GeneralResult code of the POWER OFF CARD proactive command. 



CatPowerOffCard issues the proactive command POWER OFF CARD that turns off the supplementary card reader. 

5.6.3 CatPerformCardAPDU 

CatGeneralResult 

CatPerformCardAPDU (CatDevice DevicelD, 

BYTE CAPDULength, const void *CAPDU, 

BYTE *RAPDULength, void *RAPDU) ; 



DevicelD 


[in] 


CAPDU 


[in] 


CAPDULength 


[in] 


RAPDU 


[out] 


RAPDULength 


[out] 


RETURN 





The device to send the command APDU (C-APDU) to. An acceptable value 
for this parameter is a card reader device selected from CatDevice . 
Pointer to the command C-APDU to be sent to the additional card 

device. 

The number of bytes in the C-APDU. 

Pointer to the buffer that will contain the response APDU (R-APDU) returned 

by the card in the additional card reader. You must allocate enough space to 

hold the R-APDU sent by the card. 

The number of bytes returned by the card in the additional card reader. 

The GeneralResult code of the PERFORM CARD APDU proactive 

command. 



CatPerformCardAPDU issues the proactive command PERFORM CARD APDU that sends application program data 
units (APDU) to the supplementary card reader. The terminal response is parsed and if successful the RAPDU and 
RAPDULength parameters are updated. 

5.6.4 CatGetReaderStatus 

CatGeneralResult 

CatGetReaderStatus (CatDevice DevicelD, CatReaderStatusOptions Options, 
BYTE *Status) ; 



ETSI 



3GPP TS 31.131 version 8.0.0 Release 8 22 ETSI TS 131 131 V8.0.0 (2009-04) 



DevicelD 


[in] 


Options 


[in] 


Status 
RETURN 


[out] 



Device to detect status of. An acceptable value for this parameter is a card reader 

device selected from CatPevice . 

Selects what type of status information to return. An acceptable value for this 

parameter is selected from CatGetReaderStatusOptions . 

Status of additional card reader. 

The GeneralResult code of the GET READER STATUS proactive command. 



CatGetReaderStatus issues the proactive command GET READER STATUS that retrieves the status of the additional 
card readers on the ME. The terminal response is parsed and if successful the Status parameter is updated. 

5.7 Dice File Store Access 

The abstract type FID is used to denote the file and a set of pre-processor macros are defined that enumerate all of the 
standard files of a NAA file store. A FID could be implemented as an unsigned 16-bit number as follows: 

typedef unsigned short FID; 

- #define FID_MF OxSFOO 

The starting file-context of a toolkit application is the MF. When a Doolkit application exits, the file-context is lost. 

The Access Control privileges of the application are granted during installation according to the level of trust. When an 
application requests access to UICC or operator specific files, the Toolkit Framework checks if this access is allowed by 
examination of the file control information stored on the card. If access is granted the Toolkit Framework will process 
the access request, if access is not granted, an appropriate status word will be returned. 

Contents and coding of the file(s) containing access control information are defined in ETSI TS 102 221 [12]. 

All UICC functions return the status bytes according to ETSI TS 102 221 [12], where 90 00 represents success. 

5.7.1 CatSelect 

UINT16 

CatSelect (CatFID Fileldentifier , CatFileStatus *Status) ; 



Fileldentifier 


[in] 


Status 


[out] 


RETURN 





The file to select. 
Useful Information about the directory or file If It Is successfully 

selected. 

The returned 16-blt unsigned value Is a concatenation of the SW 

response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatSelect selects the specified file as the current working file. 

5.7.2 CatStatus 

UINT16 

CatStatus (CatFileStatus *Status) ; 



NumBytes [out] The number of bytes written. 

Status [out] The status of the currently selected file. 

The returned 16'blt unsigned value Is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatStatus returns the file status of the currently selected file as specified in ETSI TS 102 221 [12]. 
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5.7.3 CatGetCHVStatus 

void 

CatGetCHVStatus (BYTE CHVStatus [4] ) ; 



ri-iv^tnt Q r ti Updates the CHVStatus array with the statusof CHV1 , CHV2, 

^^^^^ UNBL0CKCHV1 , and UNBL0CKCHV2 with CHV1 at array element zero. 



CatGetCHVStatus returns the current CHV status values. The format of the returned bytes is specified in 
ETSITS 102 221 [12]. 

5.7.4 CatReadBinary 

UINT16 

CatReadBinary (DWORD Offset, 

DWORD * NumBytes, 

void *Buffer) ; 



Offset 


[in] 


NumBytes 


[in/out] 


Buffer 


[out] 


RETURN 





The offset Into the file. 

The number of bytes to be read on input and the actual number read on 

output 

The buffer into which the data is written. 

The returned 16-bit unsigned vaiue is a concatenation of the SW 

response bytes with SW1 as the high byte and SW2 as the iow byte, so 

a successful execution wouid return 0x9000. 



CatReadBinary reads NumBytes from position Offset in the currently selected file into Buffer. 

5.7.5 CatUpdateBinary 

UINT16 

CatUpdateBinary (DWORD Offset, 

DWORD NumBytes, 

const void *Buffer) ; 



Offset 

NumBytes 

Buffer 

RETURN 


[in] 
[in] 
[in] 


The offset into the fiie. 
The number of bytes to write. 

The buffer containing the data to write to the fiie. 

The returned 16-bit unsigned vaiue is a concatenation of the SW 

response bytes with SW1 as the high byte and SW2 as the iow byte, so 

a successful execution would return 0x9000. 



CatUpdateBinary writes NumBytes contained in Buffer to position Offset in the currently selected file. 

5.7.6 CatRead Record 

UINT16 

CatReadRecord (DWORD RecordNumber, 

CatRecordAccessMode Mode, 

DWORD Offset, DWORD * NumBytes, 

void *Buffer) ; 
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RecordNumber 


[in] 


Mode 


[in] 


Offset 


[in] 


NumBytes 


[in/out] 


Buffer 


[out] 


RETURN 





The record number from which to read when Mode is ABSOLUTE or 

otherwise. 

Indication of which record is to be read; viz. NEXT, PREVIOUS, CURRENT 

or ABSOLUTE. 

The offset into the record. 

The number of bytes to be read from the record on input and the number of 

bytes actually read on output 

The buffer into which the data is read. 

The returned 16-bit unsigned vaiue is a concatenation of the SW 

response bytes with SW1 as the high byte and SW2 as the iow byte, so 

a successfui execution wouid return 0x9000. 



CatReadRecord reads NumBytes from the record RecordNumber of the currently selected file into Buffer. 

5.7.7 CatUpdateRecord 

UINT16 

CatUpdateRecord (DWORD RecordNumber , 

CatRecordAccessMode Mode, 

DWORD Offset, DWORD NumBytes, 

const void *Buffer) ; 



RecordNumber 


[in] 


The record number to which to write when l\/lode is ABSOLUTE or 

otherwise 


Mode 


[in] 


Indication of which record is to be read; viz. NEXT, PREVIOUS, CURRENT 
or ABSOLUTE. 


Offset 


[in] 


The offset into the record. 


NumBytes 


[in] 


The number of bytes to write into the record. 


Buffer 


[out] 


The buffer containing the data to write to the record. 
The returned 16-bit unsigned vaiue is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the iow byte, so 
a successfui execution wouid return 0x9000. 



CatUpdateRecord writes NumBytes into the record RecordNumber of the currently selected file from Buffer. 

5.7.8 CatSearch 

UINT16 

CatSearch (CatSearchModes Mode, 

DWORD Offset, DWORD PatternLength, 

const void * Pattern) ; 







Defines the seelc method, One of 






SEEK FROl\/l BEGINNING FORWARD, 


Mode 


[in] 


SEEK FROM END BACKWARD, 

SEEK FROM NEXT FORWARD, 

SEEK FROM PREVIOUS BACKWARD 


Offset 


[in] 


The offset into the record at which to being pattern matching. 


PatternLength 


[in] 


The size in bytes of the pattern to search for. 


Pattern 


[in] 


The buffer containing the pattern to search for. 
The returned 16-bit unsigned value is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the low byte, so 
a successful execution would return 0x9000. 



CatSearch searches records in the currently selected file starting at Offset for the pattern of length PatternLength 
contained in Pattern. If the pattern is found the current record is set appropriately. 

5.7.9 Catlncrease 

UINT16 

Catlncrease (DWORD Increment, 
DWORD *Value) ; 
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Increment 


[in] 


The value to Increase by. 


Value 


[out] 


The new value. 
The returned 16-bit unsigned value is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the low byte, so 
a successful execution would return 0x9000. 



Catlncrease adds Increment to the current record of the selected cylic file and returns the new Value. The most 
significant byte of Increment is ignored. 

5.7.10 Catlnvalidate 

UINT16 

Catlnvalidate (void) ; 



The returned 16-bit unsigned value is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



Catlnvalidate invalidates the selected file. 



5.7.11 CatRehabilitate 

UINT16 

CatRehabilitate (void) ; 



The returned 16-bit unsigned value is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatRehabilitate rehabilitates the selected file. 

5.8 Miscellaneous 
5.8.1 CatGetTerminal Profile 

void 

CatGetTerminalProfile (BYTE *ProfileOutLength, BYTE ^Profile) , 



ProfileOutLength [out] The number of bytes written to Profile. 

Profile [out] The address at which the terminal profile is written. 



CatGetTerminalProfile returns the stored terminal profile in Profile. 

5.8.2 CatMoreTime 

CatGeneralResult 
CatMoreTime (void) ; 



I RETURN The GeneralResult code of the MORE TIME proactive command. \ 

CatMoreTime issues the proactive command MORE TIME to the ME that it needs more time to process an application. 

5.8.3 CatPollingOff 

CatGeneralResult 
CatPollingOff (void) ; 
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I RETURN The GeneralResult code of the POLLING OFF proactive command. \ 

CatPollingOff issues the proactive command POLLING OFF that disables proactive polHng; this essentially turns off 
CatPollInterval. 

5.8.4 CatPollInterval 

CatGeneralResult 

CatPollInterval (CatTimeUnit Unit, BYTE Interval, 

CatTimelnterval *ActualIntervalOut) ; 



Unit 


[in] 


Interval 


[in] 


ActuallntervalOut 


[out 


RETURN 





Desired time interval. Acceptable values for this parameter are listed in 
CatTimeUnit . 
Interval in units. 

Response from ME negotiating the interval. This may or may not be the 
same as Unit an6 Interval. The value returned is in a structure of type 
CatTimelnterval . 
The GeneralResult code of the POLL INTERVAL proactive command. 



CatPollInterval issues the proactive command POLL INTERVAL that requests the ME to set a time interval between 
status application program data units (APDU) that the ME sends to the UICC. The ME responds with a time interval of 
its own that most closely matches the application programming interface (API) request. 

Polling can be disabled by using CatPollingOjf. 

5.8.5 GatRefresh 

CatGeneralResult 

CatRefresh (CatRef reshOptions Options) ; 

CatGeneralResult 

CatRefreshWithFileList (CatRef reshOptions Options, 

BYTE FileListLength, 

const void *FileList) ; 



Options [in] 



FileListLength 


[in] 


FileList 


[in] 


RETURN 





Informs the ME of what needs refreshing. Acceptable values for this 

parameter are listed in CatRefreshOptions . 

The length, in bytes, of FileList. 

The file identifiers of the files that have changed. 

The GeneralResult code of the REFRESH proactive command. 



CatRefresh issues the proactive command REFRESH that informs ME that the NAA has changed configuration due to 
UICC activity (such as an application running). 

5.8.6 CatLanguageNotification 

void 

CatLanguageNotification (CatLanguageNotif icationOptions Options, 

const void * Language) ; 



Language options. An acceptable value for this parameter is a card reader 
device selected from CatLanquaqeNotificationOptions . 

The 2'Character language code as defined by ISO 639 [5], encoded 
using SI\/IS default T-bit coded alphabet as defined by TS 23.038 [6]. 
RETURN ™^ GeneralResult code of the LANG U A GE NOTIFICA TION proactive 

command. 



Options [in] 

Language [in] 



CatLanguageNotification issues the proactive command LANGUAGE NOTIFICATION that notifies the ME about the 
language currently used for any text string within proactive commands or envelope command responses. 
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5.8.7 CatLaunchBrowser 

CatGeneralResult 

CatLaunchBrowser (CatLaunchBrowserOptions Options, 

BYTE TitleLength, const void * Title, 

BYTE URLLength, const void *URL, 

const Catlconldentif ier * Iconldentifier) , 



Options 

TitleLength 
Title 

URLLength 
URL 

Iconldentifier 



RETURN 



[in] 

[in] 
[in] 
[in] 
[in] 

[in] 



Options used to launch the browser. Acceptable values for this parameter 

are listed in CatLaunchBrowserOptions . 

The length in bytes of the string Title 

String to display on the ME during the user confirmation phase. 

The length in bytes of URL. 

The URL to open the browser at. 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon identifier 

is sent to the ME. 

The GeneralResult code of the LAUNCH BROWSER proactive 

command. 



CatLaunchBrowser and CatLaunchBrowserEx issue the proactive command LAUNCH BROWSER that launches a 
browser on the ME. 

CatGeneralResult 

CatLaunchBrowserEx (const CatLaunchBrowserExParams *params) ; 

The Structure CatLaunchBrowserExParams has the following members: 

typedef struct 

{ 

// Mandatory fields 
CatLaunchBrowserOptions Options, 
BYTE URLLength; 
const void *URL; 
// Optional fields 
BYTE BrowserldentityLength; 
const void *BrowserIdentity; 
BYTE BearerLength; 
const BYTE *Bearer; 

BYTE NumProvisioningFileRef erences ; 
BYTE *ProvisioningFileRef erenceLengths ; 
const BYTE **ProvisioningFileRef erences ; 
BYTE GatewayProxyldLength; 
const void * GatewayProxyld; 
CatAlphaString Title; 
Catlconldentifier Iconldentifier; 
} CatLaunchBrowerExParams ; 

with the following members: 



URLLength 

URL 

BrowserldentityLength 

Browserldentity 

BearerLength 

Bearer 

NumProvisioningFileReferences 
ProvisioningFileReferenceLengths 
ProvisioningFileReferences 
GatewayProxyldLength 

GatewayProxyld 

Title 

Iconldentifier 



The length in bytes of URL. 
The URL to open the browser at. 
Length in bytes of Browserldentity. 
The browser identity. If Browserldentity is NULL, no BROWSER 

IDENTITY TL V is sent to the ME. 
Length in bytes of Bearer. 

The list of bearers in order of priority requested. The type CatBearer 
defines the values acceptable. If Bearer \s NULL, no BEARER TLV is 
sent to the ME. 

The number of Provisioning File References. 
A pointer to the array of Provisioning File References lengths. 
A pointer to the array of Provisioning File References. 
Length in bytes of GatewayProxyld. 

The gateway or proxy identity. If GatewayProxyld '\s NULL, no TEXT 
STRING TLV describing the gateway/proxy is sent to the ME. 
String to display on the ME; see CatAlphaString . 
Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier.Uselcon is zero, no icon identifier is sent to the ME. 
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5.9 Low- 1 eve I Interface 

This subclause presents a low-level programming interface that allows you to: 

- Construct proactive commands and send them to the ME. 

- Access the terminal response from the ME. 

- Search the terminal response and contents of envelopes for specified TLVs. 

- Unpack the contents of envelopes from the ME and send responses. 

These functions are provided so that functionality that is not provided in the high level API is still accessible. All of 
these functions work on a single data buffer that has a single data pointer and can only be accessed sequentially. The 
high-level proactive functions may make use of the data buffer so consequently the high-level proactive functions 
should not be used whilst using the low-level functions. 

5.9.1 CatResetBuffer 

void 

CatResetBuffer (void) ; 

This function resets the data pointer to the beginning of the buffer. 

5.9.2 CatStartProactiveCommand 

void 

CatStartProactiveCommand (BYTE Command, 

BYTE Options, 

BYTE To) ; 



Command [in] Command byte of proactive command. 
Options [in] Command options of proactive command. 
To [in] The destination device identity. 



CatStartProactiveCommand resets the data pointer and starts the construction of a proactive command by writing the 
command tag, command details and device identities to the data buffer. The data pointer is left pointing after the device 
identities so that proactive command specific data can be written. 

5.9.3 CatSendProactiveCommand 

CatGeneralResult 
CatSendProactiveCommand (BYTE *Length) ; 



Lengtii [out] Pointer that is updated with the length of the terminal response 
RETURN The general result byte of the terminal response 



CatSendProactiveCommand sends the contents of the data buffer as a proactive command and updates the data buffer 
with the terminal response. The general result byte of the terminal response is returned by this function. The length of 
the terminal response is written to *Length. The data pointer is set to point to the additional information of the terminal 
response. 



5.9.4 CatOpenEnvelope 

CatEnvelopeTagType 
CatOpenEnvelope (BYTE * Length) ; 



Length [out] Pointer that is updated with the length of the envelope 
RETURN The envelope tag 
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CatOpenEnvelope returns the envelope tag of the data buffer and the length of the envelope data. The data pointer is set 
to point to the envelope data. 

5.9.5 CatSendEnvelopeResponse 

void 

CatSendEnvelopeResponse (void) ; 

CatSendEnvelopeResponse sends the contents of the data buffer as a successful envelope response. 

5.9.6 CatSendEnvelopeErrorResponse 

void 

CatSendEnvelopeErrorResponse (void) ; 

This function sends the contents of the data buffer as an unsuccessful envelope response. 

5.9.7 CatPutData 

void 

CatPutData (BYTE Length, 

const void *Data) ; 



Length [in] Length of Data 

Data [in] Pointer to Data 



CatPutData appends Length bytes of data to the data buffer. 



5.9.8 CatPutByte 

void 

CatPutByte (BYTE Data) ; 



Data [in] Data byte. 



CatPutByte appends the supplied data byte to the data buffer. 



5.9.9 CatPutTLV 

void 

CatPutTLV (BYTE Tag, 

BYTE Length, 

const void * Value) ; 



Tag [in] Tag byte. 

Length [in] Length of value. 

Value [in] A pointer to the value. 



CatPutTLV appends a general TLV to the data buffer. 



5.9.10 CatPutBytePrefixedTLV 

void 

CatPutBytePrefixedTLV (BYTE Tag, 

BYTE Prefix, 
BYTE Length, 
const void * Value) ; 
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Tag 


[in] 


Tag byte. 


Prefix 


[in] 


Prefix byte. 


Length 


[in] 


Lengtii of value. 


Value 


fin] 


A pointer to tine value. 



CatPutBytePrefixedTLV appends a TLV to the data buffer with a single byte placed before the Value. 

5.9.11 CatPutOneByteTLV 

void 

CatPutOneByteTLV (BYTE Tag, 

BYTE Value) ; 



Tag [in] Tag byte. 
Value [in] Value byte. 



CatPutOneByteTLV appends a single byte valued TLV to the data buffer. 

5.9.12 CatPutTwoByteTLV 



void 

CatPutTwoByteTLV (BYTE Tag, 

BYTE Value 1, 
BYTE Value 2) ; 



Tag [in] Tag byte. 

Valuel [in] First Value byte. 

Value2 [in] Second Value byte. 



CatPutTwoByteTLV appends a two byte valued TLV to the data buffer. 

5.9.13 CatGetByte 



BYTE 

CatGetByte (void) ; 



RETURN Data byte. 



CatGetByte returns the byte at the current data pointer and increments the data pointer by one. 



5.9.14 CatGetData 

const void * 

CatGetData (BYTE Length) ; 



Length [in] Length of Data 

RETURN Pointer to Data. 



CatGetData returns the current data pointer and increments the data pointer by Length bytes. 

5.9.15 CatFindNthTLV 

const void * 

CatFindNthTLV (BYTE Tag, 

BYTE Occurrence, 

BYTE * Length) ; 



ETSI 



3GPP TS 31.131 version 8.0.0 Release 8 31 ETSI TS 131 131 V8.0.0 (2009-04) 



Tag 


[in] 


Tag to find. 


Occurrence 


[in] 


Occurrence of Tag to find with "1 " being the first. 


Length 


[out] 


Length of found TLV. 


RETURN 




Pointer to data of found TLV 



CatFindNthTLV finds the nth TLV that matches Tag in the data buffer, where nth is specified by the Occurrence 
parameter. If a match is found the data pointer is updated to the found TLV, the function returns a pointer to the found 
value and updates Length with the data length. If no match was found the function returns the null pointer and the data 
pointer is left unchanged. 

5.9.16 CatFindNthTLVInUserBuffer 

const void * 

CatFindNthTLVInUserBuffer (BYTE BufferLen, 

const void *Buffer, 

BYTE Tag, 

BYTE Occurrence, 

BYTE *Length) ; 



BufferLen 

Buffer 

Tag 

Occurrence 

Length 

RETURN 


[in] 
[in] 
[in] 
[in] 
[out] 


Length of buffer 

Buffer to search 

Tag to find. 

Occurrence of Tag to find with "1 " being the first. 

Length of found TLV. 
Pointer to data of found TLV 



CatFindNthTLVInUserBuffer finds the nth TLV that matches Tag is the supplied buffer. The function returns a pointer 
to the found value and updates Length with the data length. If no match was found the function returns the null pointer. 

5. 1 Network Services 
5.10.1 CatGetLocationlnformation 

CatGeneralResult 

CatGetLocationlnformation (CatLocationlnformation *LocationIn format ion) ; 



,,.,,,. r ,, A pointer to where the location information from the IVIE is placed. Refer to 

Location Information out *u /^^+i ^^^n^f^ ^+-^^ *■ ^ u ^ * i 

^ ^ the CatLocallnformation section for member details. 

RETURN ^^^ GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 

The GeneralResult code of the DISPLAY TEXT proactive command. 



CatProvideLocationlnformation requests the ME to send location information to the (U)SIM using the PROVIDE 
LOCAL INFORMATION proactive command. 

5.10.2 CatGetTimingAdvance 

CatGeneralResult 

CatGetTimingAdvance (CatTimingAdvance * TimingAdvance) ; 



_ . . . A pointer to where the timing advance information from the ME is placed. 

imingAOvance [outj ^^^^^ ^^ ^^^ CatTimingAdvance section for member details. 

RETURN ^^^ GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatProvideTiming Advance requests the ME to send timing advance information to the (U)SIM using the PROVIDE 
LOCAL INFORMATION proactive command. 
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5.10.3 CatGetlMEl 

CatGeneralResult 
CatGetlMEl (BYTE IMEI[8])j 



IMEI [out] A pointer to where the IMEI of the ME is placed. 

RETURN ^^^ GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatGetlMEl requests the ME to send the IMEI to the (U)SIM using the PROVIDE LOCAL INFORMATION proactive 
command. 

5.10.4 CatGetNetworkMeasurementResults 

CatGeneralResult 

CatGetNetworkMeasurementResults (BYTE MeasurementResults [10] ) } 



MeasurementResults [out] A pointer to where the network measurement results from the ME is placed. 

RETURN ^^^ GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatGetNetworkMeasurementRe suits requests the ME to send the network measurement results to the (U)SIM using the 
PROVIDE LOCAL INFORMATION proactive command. 

5.10.5 CatGetDateTimeAndTimeZone 

CatGeneralResult 

CatGetDateTimeAndTimeZone (BYTE DateTimeAndTimeZone[7]) } 



DateTimeAndTimeZone [out] A pointer to where the date, time, and time zone from the ME is placed. 

RETURN ^^^ GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatGetDateTimeAndTimeZone s requests the ME to send the date, time, and time zone information to the (U)SIM usin^ 
the PROVIDE LOCAL INFORMATION proactive command. 

5.10.6 CatGetLanguage 

CatGeneralResult 

CatGetLanguage (BYTE Language [ 2 ]) ; 



DateTimeAndTimeZone [out] A pointer to where the language from the ME is placed. 

RETURN ^^^ GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatGetLanguage requests the ME to send the language information to the (U)SIM using the PROVIDE LOCAL 
INFORMATION proactive command. 

5.10.7 CatSetupCall 

CatGeneralResult 

CatSetupCall (BYTE CallSetupMessageLength, const void * CallSetupMessage , 

CatTypeOfNumberAndNumberingPlanldentif ier TONandNPI , 

BYTE DiallingNumberLength, const void *DiallingNumber, 

CatSetupCallOptions Options, 

const Catlconldentif ier *UserConfirmationIconIdentifier, 

BYTE CallSetupMessageLength, const void * CallSetupMessage, 

const Catlconldentif ier *CallSeupIconIdentifier) ; 
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UserConfirmationMessageLength 
UserConfirmationMessage 

TONandNPI 

DiallingNumberLength 
DialingNumber 

Options 

UserConfirmationlconldentifier 

CallSetupMessageLength 
CallSetupMessage 

CallSetuplconldentifier 

RETURN 



[in] 
[in] 

[in] 

[in] 
[in] 

[in] 



[in] 

[in] 
[in] 

[in] 



Length in bytes of UserConfirmationMessage. 

IVIessage to display for user confirmation or NULL. 

Acceptable values for this parameter are listed in 

CatTvpeOfNumberAndNumberinqPianldentifier . 

Length in bytes of DiaiiingNunfiber. 

Number to call is coded as binary-coded decimal. 

Acceptable values for this parameter are listed in 

CatSetupCaiiOptions . 

Optional icon identifier to use during the user confirmation phase; see 

Catlconldentifier for member details. If 

UserConfirmationlconldentifier is NULL or if 

UserConfirmationlconldentifier.Uselcon is zero, no user confirmation 

phase icon identifier is sent to the ME. 

Length in bytes of CaiiSetupMessage. 

Message to display for call set up or NULL. 

Optional icon identifier to use during the call setup phase; see 

Catlconldentifier for member details. If CallSetuplconldentifier is 

NULL or if CallSetuplconldentifier.Uselcon is zero, no call setup phase 

icon identifier is sent to the ME. 

The GeneralResult code of the SET UP CALL proactive command. 



CatSetupCall and CatSetupCallEx issue the SET UP CALL proactive command to the ME. 

CatGeneralResult 

CatSetupCallEx (const CatSetupCallExParams *Params) ; 

The type CatSetupCallExParams is defined as follows: 

typedef struct 

{ 

// Mandatory fields 
CatSetupCaiiOptions Options; 

CatTypeOfNumberAndNumberingPlanldentif ier TONandNPI ; 
BYTE DiallingNumberLength; 
const void *DialingNumber; 
// Optional fields 

CatAlphaString UserConfirmationMessage ; 
BYTE CapabilityConf igParamsLength; 
const void *CapabilityConf igParams; 
BYTE CalledPartySubaddressLength; 
const void *CalledPartySubaddress; 
CatTimelnterval RedialMaximumDuration; 
CatlconOption UserConf irmationlcon; 
CatAlphaString CallSetupMessage ; 
CatlconOptions CallSetupIcon; 
} CatSetupCallExParams; 

With the following members: 
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Options 

TONandNPI 

DiallingNumberLength 
DialingNumber 

UserConfirmationMessage 

CapabilityConfigParamsLength 
CapabilityConfigParams 
CalledPartySubaddressLength 
CalledPartySubaddress 

RedialMaximumDuration 

UserConfirmationlcon 

CallSetupMessage 
CallSetuplcon 



Acceptable values for this parameter are listed in CatSetupCaiiOptions . 
Acceptable values for this parameter are listed in 
CatTvpeOfNumberAndNumberinqPianldentifier . 
Length in bytes of DiallingNumber. 
Number to call is coded as binary-coded decimal. 
String to display during the user confirmation phase; see CatAJphaString . 
If this parameter is null, no user confirmation message TLV is passed to 
the ME. 

Length in bytes of CapabilityConfigParams. 

A pointer to the capability configuration parameters as coded for EFccp- 
Length in bytes of CalledPartySubadc/ress. 
The called party subaddress. 

An optional maximum duration for the redial mechanism. If the timelnterval 

member of this structure is zero, no duration TLV is sent to the ME. 

The icon to display during thie user confirmation ptiase. If ttie 

Uselcon member of thiis structure is zero, no user confirmation icon 

TLV is sent to tiie ME. 

String to display during the call set up phase; see CatAJphaString . 

The icon to display during the call setup phase. 



Optional parameters are specifically chosen to use an all-zero binary representation. This means that it is simple to set 
up only the required members of the SetupCallExParams structure by zeroing the whole structure using memset, filling 
in the required members, and sending the result to CatSetupCallEx. As all optional parameters use a zero binary 
representation, the memset serves to initialise them all to the "not present" status. 

5.10.8 CatSendShortMessage 

CatGeneralResult 

CatSendShortMessage (BYTE TitleLength, const void * Title, 

CatTypeOfNumberAndNumberingPlanldentif ier TONandNPI, 

BYTE AddressLength, const void *Address, 

BYTE SmsTPDULength, const void *SmsTPDU, 

CatSendShortMessageOptions Options, 

const Catlconldentif ier * Iconldentifier) ; 



TitleLength 


[in] 


Title 


[in] 


TONandNPI 


[in] 


AddressLength 


[in] 


Address 


[in] 


SmsTPDULength 


[in] 


SmTPDU 


[in] 


Options 


[in] 


Iconldentifier 


[in] 


RETURN 





Length in bytes of Title. 

String to display while ME is sending a message. 

Acceptable values for this parameter are listed in 

CatTypeOfNumberAndNumberinqPianldentifier . 

Length in bytes of Address. 

Address of the service center where message is being sent. 

Length in bytes of SmsTPDU. 

Formatted short message service (SMS) message to send. 

Specifies who packs the message. Acceptable values for this parameter are 

listed in CatSendShortMessageOptions . 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 

sent to the ME. 

The GeneralResult code of the SEND SHORT MESSAGE proactive 

command. 



CatSendShortMessage issues the SEND SHORT MESSAGE proactive command. 

5.10.9 CatSendSS 

CatGeneralResult 

CatSendSS (BYTE TitleLength, const void *Title, 

CatTypeOfNumberAndNumberingPlanldentif ier TONandNPI, 
BYTE SSStringLength, const void *SSString, 
const Catlconldentifier * Iconldentifier) ; 
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TitleLength 


[in] 


Length in bytes of Title. 


Title 


[in] 


String to display while ME is sending a message. 


TONandNPI 


rin1 


Acceptable values for this parameter are listed 


[inj 


CatTvDeOfNumberAndNumberinaPlanldentifier. 


SSStringLength 


[in] 


Length in bytes of SSString. 


SSString 


[in] 


SS string to ME. 

Optional icon identifier; see Catlconldentifier for member details. If 


Icon Identifier 


[in] 


Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 
sent to the ME. 


RETURN 




The GeneralResult code of the SEND SS proactive command. 



CatSendSS issues the SEND SS proactive command to the ME. 

5.10.10 CatSendUSSD 

CatGeneralResult 

CatSendUSSD (BYTE TitleLength, const void * Title, 

CatDCSValue MessageDCS, BYTE MessageLength, const void *Message, 
CatDCSValue *MsgOutDCS, BYTE *MsgOutLength, void *MsgOut, 
const Catlconldentifier * Iconldentifier) ; 



TitleLength 


[in] 


The length in bytes of Title. 


Title 


[in] 


String to display while ME is sending a message. 


MessageDCS 


[in] 


The data-coding scheme for Message. Acceptable values for this parameter 
are listed in CatDCSValue. 


MessageLength 


[in] 


The length in bytes of Message. 


Message 


[in] 


Message to send. 


MsgOutDCS 


[out] 


Identifies type of DCS for the returned message. 


MsgOutLength 


[out] 


Length of the returned message in bytes. 


MsgOut 


[out] 


Returned string or message. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 
sent to the ME. 


RETURN 




The GeneralResult code of the SEND USSD proactive command. 



CatSendUSSD issues the SEND USSD proactive command. The terminal response is parsed and if successful the 
MsgOutDCS, MsgOutLength and MsgOut parameters are updated. 



5.10.11 CatOpenCSChannel 



CatGeneralResult 

CatOpenCSChannel (CatOpenChannelOptions Options, 

BYTE UserConfirmationLength, const void *UserConfirmation, 

const Catlconldentifier *UserConfimationIconIdentifier, 

CatTypeOfNiimberAndNiimberingPlanldentif ier TONandNPI , 

BYTE DiallingNumberLength, const void *DiallingNumber, 

BYTE BearerDescription [3] , 

UINT16 *BufferSize, 

CatDevice * Channel Identifier) ; 
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Options [in] 

UserConfirmationLength [in] 

UserConfirmation [in] 



UserConfirmationlconldentifier [in] 



TONandNPI [in] 

DiallingNumberLength [in] 

DialingNumber [in] 

BearerDescription [i n/out] 



BufferSize [in/out] 

Channelldentifier [out] 

RETURN 



Acceptable values for this parameter are listed in 

CatOpenChanneiOptions . 

Length in bytes of UserConfirmation. 

String to display when ME alerts user that channel is to be opened. 

Optional icon identifier to use during the user confirmation phase; see 

Catlconldentifier for member details. If 

UserConfirmationlconldentifier is NULL or if 

UserConfirmationlconldentifier.Uselcon is zero, no user confirmation 

phase icon identifier is sent to the ME. 

Acceptable values for this parameter are listed in 

CatTypeOfNumberAndNumberinqPianldentifier . 

Length in bytes of DiaiiingNumber. 

Number to call is coded as binary-coded decimal. 

Initially contains the bearer description parameters (data rate, bearer 

service and connection element) and is modified to the actual bearer 

description as allocated by the ME. 

Initially contains the desired buffer size and is modified to the actual 

buffer size as allocated by the ME. 

The channel identifier that has been allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatGeneralResult 

CatOpenCSChannelEx (const CatOpenCSChannelExParams *Params, 
CatDevice * Channelldentifier, 
BYTE BearerDescription [3] , 
UINT16 * BufferSize) ; 



Params 
Clianneildentifier 

BearerDescription 

BufferSize 

RETURN 



[in] 
[out] 

[out] 

[out] 



Constant parameter set as defined below. 

The channel identifier that has been allocated by the ME. 

An array to which the actual bearer description allocated by the ME 

will be written. 

The actual buffer size allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatOpenCSChannel and CatOpenCSChannelEx issue the proactive command OPEN CHANNEL related to a CS 
bearer. The terminal response is parsed and if the command was successful the BearerDescription, BufferSize and 
Channelldentifier parameters are updated. 

The type CatOpenCSChannelExParams is defined as follows: 

typedef struct 

{ 

// Mandatory fields 
CatOpenChanneiOptions Options; 
BYTE AddressLength; 
const BYTE *Address; 
BYTE BearerDescription [3] ; 
UINT16 BufferSize; 
// Optional fields 

CatAlphaString UserConf irmationMessage ; 
Catlconldentifier UserConfirmationlconldentifier; 
BYTE SubAddressLength; 
const BYTE *SubAddress; 
BYTE DurationlDef ined; 
CatTimelnterval Durationl; 
BYTE Duration2Def ined; 
CatTimelnterval Duration2; 
CatAddressType LocalAddress; 
CatTextString UserLogin; 
CatTextString UserPassword; 

CAT_MEInterfaceTransportLevelType CAT_MEInterf aceTransportLevel ; 
CatAddressType DataDestinationAddress ; 
} CatOpenCSChannelExParams; 

With the following members: 
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Options 

AddressLength 
Address 

BearerDescription 

BufferSize 



UserConfirmationMessage 



UserConfirmationlconldentifier 

SubAddressLength 

SubAddress 

Durationi Defined 

Duration 1 

Duration2Defined 

Duration2 

LocalAddress 

UserLogin 

UserPassword 

CA T_MEInterface TransportLevel 

DataDestinationAddress 



Acceptable values for this parameter are listed in 
CatOpenChannelOptions . This field is mandatory. 
Length in bytes of Address. This field is mandatory. 

The address to call. This field Is mandatory. 
The desired bearer parameters (data rate, bearer service and 
connection element). This field Is mandatory. 
The desired buffer size. This field is mandatory. 

String to display during the user confirmation phase; see CatAlphaStrinq . 
If this parameter is null, no user confirmation message TLV is passed to 
the ME. If UserConfirmationMessage is not null but 
UserConfirmationMessageLength is zero, a user confirmation message 
TLV is passed to the ME with the length component set to zero. 

The Icon to display during the user confirmation phase. If the 
Uselcon member of this structure Is zero, no user confirmation Icon 
TLV Is sent to the ME. 
Length in bytes of SubAddress. 
The subaddress to call. 
Set to nonzero if Durationi is defined. 

Duration of reconnect tries; see CatTlmelnterval . 

Set to nonzero If Duratlon2 Is defined. 

Duration of timeout; see CatTlmelnterval . 

The LocalAddress; see CatAddressType . 

The user login string. 

The user password string. 

See CAT MEInterfaceTransportLeveJType . 

The DataDestinationAddress; see CatAddressType. 



5.10.12 CatOpenGPRSChannel 



CatGeneralResult 

CatOpenGPRSChannel (CatOpenChannelOptions Options, 

BYTE UserConfirmationLength, const void *UserConfirmation, 

const Catlconldentif ier *UserConfirmationIconIdentifier, 

BYTE BearerDescription [8] , 

UINT16 *BufferSize, 

CatDevice * Channel Identifier) ; 



Options [in] 

UserConfirmationLengtIi [in] 

UserConfirmation [in] 



UserConfirmationlconldentifier [i n] 



BearerDescription [i n/out] 

BufferSize [in/out] 

Cliannelidentifier [out] 
RETURN 



Acceptable values for this parameter are listed in 

CatOpenChannelOptions . 

Length in bytes of UserConfirnfiation. 

String to display when ME alerts user that channel is to be opened. 

Optional icon identifier to use during the user confirmation phase; see 

Catlconldentifier for member details. If 

UserConfirmationlconldentifier \s NULL or if 

UserConfirmationlconldentifier.\Jse\con is zero, no user confirmation 

phase icon identifier is sent to the ME. 

Initially contains the bearer description and is modified to the actual 

bearer description as allocated by the ME. 

Initially contains the desired buffer size and is modified to the actual 

buffer size as allocated by the ME. 

The channel identifier that has been allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatGeneralResult 

CatOpenGPRSChannelEx (const CatOpenGPRSChannelExParams *Params, 
CatDevice *ChannelIdentifier, 
BYTE ActualBearerDescription [8] , 
UINT16 *ActualBufferSize) ; 
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Params 


[in] 


Channelldentifier 


[out] 


ActualBearerDescription 


[out] 


Actual BufferSize 


[out] 


RETURN 





Constant parameter set as defined below. 

The channel identifier that has been allocated by the ME. 

An array to which the actual bearer description allocated by the ME 

will be written. 

The actual buffer size allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatOpenGPRSChannel and CatOpenGPRSChannelEx issue the proactive command OPEN CHANNEL related to a 
GPRS bearer. The terminal response is parsed and if the command was successful the BearerDescription, BufferSize 
and Channelldentifier parameters are updated. 

The type CatOpenGPRSChannelExParams is defined as follows: 

typedef struct 

{ 

// Mandatory fields 
GsmOpenChannelOptions Options; 
BYTE AddressLength; 
const BYTE *Address; 
BYTE BearerDescription [8] ; 
UINT16 BufferSize; 
// Optional fields 

CatAlphaString UserConf irmationMessage ; 
Catlconldentif ier UserConf irmationi conldent if ier; 
BYTE AccessPointNameLength; 
const BYTE *AccessPointName; 
CatAddressType LocalAddress; 

CAT_ME_InterfaceTransportLevelType CAT_ME_Interf aceTransportLevel ; 
CatAddressType DataDestinationAddress ; 
} GsmOpenGPRSChannelExParams; 

With the following members: 



Options 

AddressLength 
Address 

BearerDescription 
BufferSize 



UserConfirnfiationlVlessage 



UserConfirmationlconldentifier 

AccessPointNameLengtti 

AccessPointName 

LocalAddress 

CA T_ME_lnterface TransportLevel 

DataDestinationAddress 



Acceptable values for this parameter are listed in 
CatOpenChannelOptions . This field is mandatory. 
Length in bytes of Address. This field is mandatory. 

The address to call. This field Is mandatory. 
The desired bearer. This field Is mandatory. 
The desired buffer size. This field is mandatory. 

String to display during the user confirmation phase; see CatAlphaString . 
If this parameter is null, no user confirmation message TLV is passed to 
the ME. If UserConfirmationMessage is not null but 
UserConfirmationMessageLength is zero, a user confirmation message 
TLV is passed to the ME with the length component set to zero. 

The icon to display during the user confirmation phase. If the 

Uselcon member of this structure is zero, no user confirmation icon 

TLV is sent to the ME. 

The length in bytes of AccessPoint. 

The Access Point Name. 

See CatAddressType . 

See CAT MEInterfaceTransportLevelType . 

See CatAddressType. 
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5.10.13 CatCloseChannel 

CatGeneralResult 

CatCloseChannel (CatDevice Channelldentifier, 

BYTE TitleLength, const void * Title, 

const Catlconldentif ier * Iconldentifier) ; 

Channelldentifier [in] The channel identifier as returned from one of the open commands 

TitleLength [in] The length in bytes of Title. 

Title [in] String to display while ME is closing the channel. 

Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier [in] Iconldentifier \s NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 

sent to the ME. 
RETURN The GeneralResult code of the CLOSE CHANNEL proactive command. 

CatCloseChannel issues a CLOSE CHANNEL proactive command that closes an open channel 

5.10.14 CatReceiveData 

CatGeneralResult 

CatReceiveData (CatDevice Channelldentifier, 

BYTE TitleLength, const void * Title, 

BYTE RequestedChannelDataLength, 

const Catlconldentifier * Iconldentifier , 

BYTE *ChannelData, 

BYTE *NumChannelBytesRead, 

BYTE *NumChannelBytesLeft) ; 



Channelldentifier [in] The channel identifier as returned from one of the open commands 

TitleLength [in] The length in bytes of Title. 

Title [in] String to display while ME is receiving data. 

RequestedChannelDataLength [in] The number of bytes requested to be read. 

Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier [in] Iconldentifier \s NULL or if lconldentifier.\Jse\con is zero, no icon 

identifier is sent to the ME. 
ChannelData [out] Received channel data. 

NumChannelBytesRead [out] The number of bytes received as channel data. 

The number of bytes remaining to be read from the channel buffer, or 

255 if there are more than 255 bytes left to be read. 
RETURN The GeneralResult code of the RECEIVE DATA proactive command. 



NumChannelBytesLeft [out] 



CatReceiveData issues a RECEIVE DATA proactive command that receives data from an open channel The terminal 
response is parsed and if the command is successful the received data is copied into the ChannelData array and the 
NumChannelBytesRead and NumChannelBytesLeft parameters are updated. 

5.10.15 CatSendData 

CatGeneralResult 

CatSendData (CatDevice Channelldentifier, 
CatSendDataOptions Options, 

BYTE TitleLength, const void * Title, 

BYTE ChannelDataLength, 

const void * ChannelData, 

const Catlconldentifier * Iconldentifier , 

BYTE *ActualBytesSent) ; 
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Options [in] 



Channelldentifier [in] The channel identifier as returned from one of the open commands 

TitleLength [in] The length in bytes of Title. 

Title [in] String to display while ME is receiving data. 

Specifies who packs the message. Acceptable values for this 

parameter are listed in CatSendPataOptions . 
ChannelDataLength [in] The number of bytes to be sent from ChannelData. 

ChannelData [in] The data to be sent. 

Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier [in] Icon Identifier \s NULL or if Iconldentifier.Uselcon is zero, no icon 

identifier is sent to the ME. 
.. o/c f^oC^r.f r ti The number of bytes sent (derived from the CHANNEL DATA 
Actuaibytesbent [out] LENGTH TLV in the TERMINAL RESPONSE). 
RETURN The GeneralResult code of the SEND DATA proactive command. 



CatSendData issues the proactive command SEND DATA that sends data to an open channel 

5.10.16 CatGetChannelStatus 

CatGeneralResult 

CatGetChannelStatus (CatDevice Channelldentifier, void * ChannelStatus) ; 



Channelldentifier [in] The channel identifier. 

ChannelStatus [out] Returned channel status bytes. 

RETURN '^^^ GeneralResult code of the GET CHANNEL STATUS proactive 

command. 



CatGetChannelStatus issues a proactive conmiand GET CHANNEL STATUS. The terminal response is parsed if the 
command is successful to find the status of the supplied channel. 

5.10.17 CatServiceSearch 

CatGeneralResult 

CatServiceSearch (CatBearer Bearerld, 

BYTE AttributeLength, void *Attrihutes, 
void * ServiceAvailahility) ; 



Bearerld [in] The identifier of the bearer whose services will be searched. 

AttributeLength [in] The length of the following attribute array. 

Aff.i^ fpc; \- 1 Attributes that describe bearer services, typically in a bearer specific 



Service A vai lability [in] 



format. 

List of services offered by the bearer that satisfy the attributes, 

typically in a bearer specific format. 



CatServiceSearch searches for a particular service on a bearer. 

5.10.18 CatGetServicelnformation 

CatGeneralResult 

CatGetServicelnformation (BYTE TitleLength, const BYTE * Title, 

const catlconldentifier * Iconldentifier, 

CatBearer Bearerld, 

BYTE * AttributeLength, void ^Attributes , 

void * Servicelnformation) ; 
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TitleLength 
Title 

Iconldentifier 

Bearerld 
AttributeLength 
Attributes 
Service Information 



[in] The length in bytes of Title. 

[in] String to display acquiring service information. 

Optional icon identifier; see Catlconldentifier for member details, 
[in] Iconldentifier \s NULL or if Iconldentifier.Uselcon is zero, no icon 

identifier is sent to the ME. 
[in] The identifier of the bearer whose service information is requested, 
[in] The number of bytes In the following attribute array. 

[in] Attributes describing the service information requested, 
[out] The requested information. 



CatGetServicelnformation retrieves information about a particular service on a bearer. 

5.10.19 CatDeclareService 

CatGeneralResult 

CatDeclareService (CatBearer Bearerld, BYTE Serviceld, 

CatTransportProtocol TransportProtocol , 

WORD * PortNumher , 

BYTE ServiceRecordLength, 

void * ServiceRecord) ; 



Bearerld 

TransportProtocol 

PortNumber 

ServiceRecordLength 

ServiceRecord 



[in] The identifier of the bearer for which this service is being offered. 

[in] The transport protocol on which the service is provided. 

[in] The port on which the service is provided. 

[in] The number of bytes in the following service record. 

[in] The service record describing the service. 



CatDeclareService describes a new service. 



5.10.20 CatRunATCommand 

CatGeneralResult 

CatRunATCommand (BYTE TitleLength, const void * Title, 

BYTE CommandLength, const void * Command, 
const Catlconldentifier * Iconldentifier, 
void * Response, BYTE * ResponseLength) ; 



TitleLength 


[in] 


Length in bytes of Title. 


Title 


[in] 


String to display on ME while command is executing. 


CommandLength 


[in] 


Length in bytes of Command. 


Command 


[in] 


AT command string 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier \s NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 
sent to the ME. 


Response 


[out] 


ME response string. 


ResponseLength 


[out] 


Length In bytes of ME response string. 


RETURN 




The GeneralResult code of the RUN AT COMMAND proactive 
command. 



CatRunATCommand issues the proactive command RUN AT COMMAND that sends an AT command to the ME. The 
terminal response is parsed and if successful the parameters Response and ResponseLength are updated. 

5.10.21 CatSendDTMFCommand 

CatGeneralResult 

CatSendDTMFCoinmand (BYTE TitleLength, const void *Title, 

BYTE DTMFCodeLength, const void *DTMFCode, 

const Catlconldentifier * Iconldentifier) ; 
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TitleLength 


[in] 


The length in bytes of Title. 


Title 


[in] 


Title displayed while the DTMF string is sent to the network. 


DTMFCodeLength 


[in] 


The length in bytes of DTMFCode. 


DTMFCode 


[in] 


DTMF string sent to the network. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier is NULL or if Iconldentifier. Uselcon is zero, no icon 
identifier is sent to the ME. 


RETURN 




The GeneralResult code of the SEND DTMF COMMAND proactive 

command. 



CatSendDTMF issues the proactive command SEND DTMF COMMAND that sends a dual tone multiple frequency 
(DTMF) string to the network. 

5.11 Supporting Data Types 

typedef unsigned char BYTE, 
typedef unsigned short WORD, 
typedef unsigned long int DWORD. 

5.11.1 CatRecordAccessMode 

typedef enum { 

NEXT = 0x02, 

PREVIOUS = 0x03, 

CURRENT = 0x04, 

ABSOLUTE = 0x04 
} CatRecordAccessMode; 

5.11.2 CatSearchMode 

typedef enum { 
BEGINNING_FORWARD , 
END_BACKWARD , 
NEXT_FORWARD , 
PRE VI OUS_BACKWARD 
} CatSearchMode; 

5.11.3 CatFrameworkEventType 

typedef enum 

{ 

// Command monitoring events 
EVENT_TERMINAL_PROFILE_COMMAND , 
EVENT_STATUS_COMMAND 
EVENT_ENVELOPE_COMMAND , 

// Application lifecycle events start here 
EVENT_APPLICATION_LIFECYCLE_INSTALL = 0x2 
// Framework fabricated events start here 
EVENT_UPDATE_EF_SMS = 0x4 
EVENT_PROFILE_DOWNLOAD , 
EVENT_FORMATTED_SMS_PP_UPD , 
EVENT_STATUS_COMMAND , 
EVENT_UNFORMATTED_SMS_PP_UPD , 
EVENT_MENU_SELECTION, 
EVENT_FORMATTED_SMS_PP_ENV , 
EVENT_UNFORMATTED_SMS_PP_ENV , 
EVENT_FORMATTED_SMS_PP_CB , 
EVENT_MENU_SELECTION_HELP_REQUEST, 
EVENT_CALL_CONTROL_BY_S IM , 
EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM, 
EVENT_TIMER_EXPIRATION, 
EVENT_DOWNLOAD_MT_CALL_EVENT , 
EVENT_DOWNLOAD_CALL_CONNECTED_EVENT, 
EVENT_DOWNLOAD_CALL_DISCONNECTED_EVENT, 
EVENT DOWNLOAD LOCATION STATUS EVENT, 
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EVENT_DOWNLOAD_USER_ACTIVITY_EVENT, 
EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE_EVENT, 
EVENT_DOWNLOAD_CARD_READER_STATUS_EVENT, 
EVENT_DOWNLOAD_LANGUAGE_SELECTION_EVENT, 
EVENT_DOWNLOAD_BROWSER_TERMINATION_EVENT, 
E VENT_DOWNLOAD_DATA_AVAI LABLE_E VENT , 
EVENT_DOWNLOAD_CHANNEL_STATUS_EVENT, 
EVENT_UNRECOGNIZED_ENVELOPE , 
EVENT_TERMINAL_RESPONSE , 
EVENT_APPLICATION_INSTALL 
} CatFrameworkEventType; 

5.11.4 CatEnvelopeTagType 

typedef enum { 

Siy[S_PP_DOWNLOAD_TAG = OxDl, 

CELL_BROADCAST_TAG = 0xD2 , 

MENU_SELECTION_TAG = 0xD3 , 

CALL_CONTROL_TAG = OxD4 , 

MO_SHORT_MESSAGE_CONTROL_TAG = OxD5, 

EVENT_DOWNLOAD_TAG = 0xD6 , 

TIMER_EXPIRATION = OxD7 

} CatEnvelopeTagType; 



5.11.5 CatEventType 



typedef enum { 
MT_CALL_EVENT 
CALL_CONNECTED_EVENT 
CALL_DISCONNECTED_EVENT 
LOCATION_STATUS_EVENT 
USER_ACTIVITY_EVENT 
IDLE_SCREEN_AVAILABLE 
C ARD_RE AD E R_S TATUS 
LANGUAGE_SELECTION 
BROWSER_TERMINATION 
DATA_AVAI LABLE 
CHANNEL_S TATUS 

} CatEventType; 



0x00, 
0x01, 
0x02, 
0x03, 
0x04, 
0x05, 
0x06, 
0x07, 
0x08, 
0x09, 
OxOA 



5.11.6 CatTextString 

typedef struct 

{ 

CatDCSValue DCSValue; 

BYTE TextStringLength; 

const void *TextString; 
} CatTextString; 

5.11.7 CatAlphaString 

typedef struct 

{ 

BYTE AlphaStringLength; 
const void *AlphaString; 
} CatTextString; 

5.11.8 Catlcon Identifier 

typedef struct 

{ 

BYTE Use Icon; 
BYTE Iconldentif ier; 
BYTE IconOptions; 
} Catlconldentif ier; 

The Catlconldentifier structure is defined as follows: 



ETSI 



3GPP TS 31.131 version 8.0.0 Release 8 44 ETSI TS 131 131 V8.0.0 (2009-04) 



If zero, the icon identifier is not used in the proactive command. If non- 
Uselcon zero, the Iconldentifier and IconOption members are used in the 

proactive command. 
Iconldentifier Index of the icon to display. 

Options with which to display the icon selected from CatlconOption . 

This is specified as a BYTE rather than CatlconOptios as, in C, an 
IconOptions enumeration uses the same storage as an int which is at least 16 bits, 

whereas the proactive commands that use these identifiers use 8-bit 
quantities. 



5.11.9 CatlconOption 

typedef enum 

{ 

SHOW_WITHOUT_TEXT = 0x0 0, 

SHOW_WITH_TEXT = 0x01 
} CatlconOption; 

5.11.10 CatDCSValue 

typedef enum 

{ 

DCS_SMS_PACKED = 0x0 0, 
DCS_SMS_UNPACKED = 0x04, 
DCS_SMS_UNICODE = 0x0 8 
} CatDCSValue; 

5.11.11 CatDisplayTextOptions 

typedef enum 

{ 

N0RMAL_PR10R1TY_AUT0_CLEAR = 0x0 0, 

N0RMAL_PR10R1TY_USER_CLEAR = 0x8 0, 

H1GH_PR10R1TY_AUT0_CLEAR = 0x01, 

HIGH_PRIORITY_USER_CLEAR = 0x81 

} CatDisplayTextOptions; 

5.11.12 CatGetlnKeyOptions 

typedef enum 

{ 

YES_NO_OPTION_NO_HELP = 0x04, 

YES_NO_OPTION_WITH_HELP = 0x84, 

DIGITS_ONLY_NO_HELP = 0x0 0, 

DIGITS_ONLY_WITH_HELP = 0x8 0, 

SMS_CHARACTER_NO_HELP = 0x01, 

SMS_CHARACTER_WITH_HELP = 0x81, 

UCS2_CHARACTER_N0_HELP = 0x03, 

UCS2_CHARACTER_WITH_HELP = 0x83 
} CatGetlnKeyOptions; 

5.11.13 CatGetlnputOptions 

typedef enum 

{ 

PACKED_DIGITS_ONLY_NO_HELP = 0x0 8, 

PACKED_DIGITS_ONLY_WITH_HELP = 0x8 8, 

PACKED_DIGITS_ONLY_NO_ECHO_NO_HELP = OxOC, 

PACKED_DIGITS_ONLY_NO_ECHO_WITH_HELP = 0x8C, 

UNPACKED_DIGITS_ONLY_NO_HELP = 0x0 0, 

UNPACKED_DIGITS_ONLY_WITH_HELP = 0x8 0, 

UNPACKED_DIGITS_ONLY_NO_ECHO_NO_HELP = 0x04, 

UNPACKED_DIGITS_ONLY_NO_ECHO_WITH_HELP = 0x84, 

PACKED_SMS_ALPHABET_NO_HELP = 0x0 9, 

PACKED_SMS_ALPHABET_WITH_HELP = 0x8 9, 

PACKED_SMS_ALPHABET_NO_ECHO_NO_HELP = OxOD, 

PACKED_SMS_ALPHABET_NO_ECHO_HELP = 0x8D, 

UNPACKED SMS ALPHABET NO HELP = 0x01, 
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UNPACKED_SMS_ALPHABET_WITH_HELP = 0x81, 

UNPACKED_SMS_ALPHABET_NO_ECHO_NO_HELP = 0x05, 

UNPACKED_SMS_ALPHABET_NO_ECHO_WITH_HELP = 0x85, 

UCS2_ALPHABET_N0_HELP = 0x03, 

UCS2_ALPHABET_WITH_HELP = 0x83, 

UCS2_ALPHABET_N0_ECH0_N0_HELP = 0x0 7, 

UCS2_ALPHABET_N0_ECH0_WITH_HELP = 0x8 7 
CatGetlnputOptions ; 



5.11.14 CatSelectltemOptions 

typedef enum 

{ 

PRE S ENT_AS_DATA_VALUE S_NO_HEL P 
PRE S ENT_AS_DATA_VALUE S_W I TH_HEL P 
PRESENT_AS_NAVIGATION_OPTIONS_NO_HELP 
PRESENT_AS_NAVIGATION_OPTIONS_WITH_HELP 
DEFAULT_STYLE_NO_HELP 
DEFAULT_STYLE_WITH_HELP 
} CatSelectltemOptions; 



0x01, 
0x81, 
0x03, 
0x83, 
0x00, 
0x80 



5.11.15 CatTimeUnit 



typedef enum 

{ 

GSM_MINUTES = 0x0 0, 

GSM_SECONDS = 0x01, 

GSM_TENTHS_OF_SECONDS = 0x02 
j CatTimeUnit; 



5.11.16 CatTone 



typedef enum 

{ 

DIAL_TONE 
CALLER_BUSY 
CONGESTION 

RAD I 0_PATH_ACKNOWLEDGE 
CALL_DROPPED 

SPECIAL_INFORMATION_OR_ERROR 
CALL_WAITING_TONE 
RINGING_TONE 
GENERAL_BEEP 

POSITIVE_ACKNOWLEDGE_TONE 
NEGATIVE_ACKNOWLEDGE_TONE 
j CatTone; 



0x01, 
0x02, 
0x03, 
0x04, 
0x05, 
0x06, 
0x07, 
0x08, 
0x10, 
0x11, 
0x12 



5.11.17 CatRef reshOptions 

typedef enum 

{ 

REFRESH_SIM_INIT_AND_FULL_FILE_CHANGE_NOTIFICATION 
REFRESH_FILE_CHANGE_NOTIFICATION 
REFRESH_SIM_INIT_AND_FILE_CHANGE_NOTIFICATION 
REFRESH_SIM_INIT 
REFRESH_SIM_RESET 
} CatRef reshOptions; 



0x00, 
0x01, 
0x02, 
0x03, 
0x04 



5.11.18 CatGetReaderStatusOptions 

typedef enum 



CARD_READER_STATUS = 0x0 0, 
CARD_READER_IDENTIFIER = 0x01 
CatGetReaderStatusOptions ; 
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5.11.19 CatDevice 

typedef enum 

{ 

DEVICE_KEPYAD = 0x01, 

DEVI CE_D I SPLAY = 0x02, 
DEVICE_EARPIECE = 0x03, 
DEVICE_CARD_READER_0 = 0x10, 
DEVICE_CARD_READER_1 = 0x11, 
DEVICE_CARD_READER_2 = 0x12, 
DEVICE_CARD_READER_3 = 0x13, 
DEVICE_CARD_READER_4 = 0x14, 
DEVICE_CARD_READER_5 = 0x15, 
DEVICE_CARD_READER_6 = 0x16, 
DEVICE_CARD_READER_7 = 0x17, 
DEVICE_CHANNEL_1 = 0x21, 
DEVICE_CHANNEL_2 = 0x22, 
DEVICE_CHANNEL_3 = 0x23, 
DEVICE_CHANNEL_4 = 0x24, 
DEVICE_CHANNEL_5 = 0x25, 
DEVICE_CHANNEL_6 = 0x26, 
DEVICE_CHANNEL_7 = 0x2 7, 
DEVICE_SIM = 0x81, 

DEVICE_ME = 0x82, 

DEVICE_NETWORK = 0x83 
} CatDevice; 

5.11.20 CatGeneral Result 

typedef enum 

{ 

CAT_COMMAND_SUCCESSFUL = 0x0 0, 

CAT_COMMAND_SUCCESSFUL_WITH_PARTIAL_COMPREHENSION = 0x01, 

CAT_COMMAND_SUCCESSFUL_WITH_MISSING_INFORMATION = 0x02, 

CAT_REFRESH_SUCCESSFUL_WITH_ADDITIONAL_EFS_READ = 0x03, 

CAT_COMMAND_SUCCESSFUL_BUT_ICON_NOT_FOUND = 0x04, 
CAT_COMMAND_SUCCESSFUL_BUT_MODIFIED_BY_CALL_CONTROL = 0x05, 

CAT_COMMAND_SUCCESSFUL_BUT_LIMITED_SERVICE = 0x06, 

CAT_COMMAND_SUCCESSFUL_WITH_MODIFICATION = 0x07, 

CAT_ABORTED_BY_USER = 0x10, 

CAT_BACKWARD = 0x11, 

CAT_NO_RESPONSE = 0x12, 

CAT_HELP_REQUIRED = 0x13, 

CAT_USSD_ABORTED_BY_USER = 0x14, 

CAT_ME_UNABLE_TO_PROCESS_COMMAND = 0x2 0, 

CAT_NETWORK_UNABLE_TO_PROCESS_COMMAND = 0x21, 

CAT_USER_REJECTED_SETUP_CALL = 0x22, 

CAT_USER_CLEARED_BEFORE_RELEASE = 0x23, 

CAT_ACTION_CONTRADICT_TIMER_STATE = 0x24, 

CAT_TEMP_PROBLEM_IN_CALL_CONTROL = 0x2 5, 

CAT_LAUNCH_BROWSER_ERROR = 0x2 6, 

CAT_COMMAND_BEYOND_ME_CAPABILITIES = 0x3 0, 

CAT_COMMAND_TYPE_NOT_UNDERSTOOD = 0x31, 

CAT_COMMAND_DATA_NOT_UNDERSTOOD = 0x32, 

CAT_COMMAND_NUMBER_NOT_KNOWN = 0x3 3, 

CAT_SS_RETURN_ERROR = 0x34, 

CAT_SMS_RP_ERROR = 0x3 5, 

CAT_REQUIRED_VALUES_MISSING = 0x36, 

CAT_USSD_RETURN_ERROR = 0x3 7, 

CAT_MULTIPLE_CARD_COMMAND_ERROR = 0x3 8, 

CAT_PERMANENT_PROBLEM_IN_SMS_OR_CALL_CONTROL = 0x3 9, 

CAT_BEARER_INDEPENDENT_PROTOCOL_ERROR = 0x3 A 

} CatGeneralResult; 
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5.11.21 CatTimerValue 

typedef struct 

{ 

BYTE hour; 
BYTE minute; 
BYTE second; 
} CatTimerValue; 

The CatTimerValue data type has three one-byte values: 



hour Hours part of timer. 

Minute Minutes part of timer. 

Second Seconds part of timer. 



5.11.22 CatTimelnterval 

typedef struct 

{ 

BYTE timeUnit; 

BYTE timelnterval; 
} CatTimelnterval; 

The CatTimlnterval data type has two one-byte values: 



One of the CatTimeUnit enumeration values. This is specified as a BYTE rather than CatTimeUnit 
timeUnit as, in C, an enumeration uses the same storage as an int which is at least 16 bits, whereas the 

proactive commands that use these identifiers use 8-bit quantities. 
Timelnterval The number of timeUnits. 



5.11.23 CatFileStatus 



typedef struct 



WORD recordLength; 
WORD numberOf Records; 
BYTE lengthOf Trailer; 
BYTE trailer [] ; 
} CatEFStatus; 

typedef struct 



BYTE numberOf DFs; 
BYTE numberofEFs; 

BYTE CHVlStatus; 

BYTE unblockCHVlStatus; 

BYTE CHV2 Status; 

BYTE unblockCHV2Status; 

BYTE lengthOf Trailer; 
BYTE trailer [] ; 
} CatDFStatus; 

typedef struct 

{ 
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DWORD totalFileSize; 

UINT16 filelD; 

BYTE f ileDescriptorByte; 

BYTE fileType; // 0=RFU, 

BYTE fileLifeCycleStatus; 

union 

{ 

CatEFStatus ef; 
CatDFStatus df; 
} u; 

CatFileStatus; 



01=MF, 02=DF, 04=EF 



5.1 1 .24 CatLanguageNotificationOptions 



typedef enum 

{ 

LANGUAGE_NON_S FECI FIC_NOTIFI CATION = 0x00, 
LANGUAGE_SPECIFIC_NOTIFICATION = 0x01 
} CatLanguageNotificationOptions ; 

5.1 1 .25 CatLocationlnformation 

typedef struct 

{ 

BYTE mobileCountryNetworkCodes [3] ; 
BYTE LAC [2] ; 
BYTE cell ID [2] ; 
j CatLocationlnformation; 



5.1 1 .26 CatTiming Advance 



typedef struct 

{ 

BYTE MEStatus; 
BYTE timingAdvance; 
} CatTimingAdvance; 



5.1 1 .27 CatLaunchBrowserOptions 

typedef enum 

{ 

LAUNCH_BROWSER_IF_NOT_ALREADY_LAUNCHED = 0x0 0, 

USE_EXISTING_BROWSER = 0x02, 

CLOSE_EXISTING_BROWSER_AND_LAUNCH_NEW_BROWSER = 0x03 

} CatLaunchBrowserOptions; 



5. 1 1 .28 CatSetupCallOptions 

typedef enum 

{ 

CALL_ONLY_I F_NOT_BUS Y 

CALL_ONLY_IF_NOT_BUSY_WITH_REDIAL 

CALL_AND_PUT_ALL_OTHER_CALLS_ON_HOLD 

CALL_AND_PUT_ALL_OTHER_CALLS_ON_HOLD_WITH_REDIAL 

CALL_AND_DISCONNECT_ALL_OTHER_CALLS 

CALL_AND_DISCONNECT_ALL_OTHER_CALLS_WITH_REDIAL 

} CatSetupCallOptions; 



0x00, 
0x01, 
0x02, 
0x03, 
0x04, 
0x05 
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5.1 1 .29 CatTypeOfNumberAndNumberingPlanldentifier 

typedef enum 

{ 

TON_UNKNOWN_AND_NPI_UNKNOWN = 0x8 0, 

TON_INTERNATIONAL_AND_NPI_UNKNOWN = 0x9 0, 

TON_NATIONAL_AND_NPI_UNKNOWN = OxAO , 

TON_NETWORK_AND_NPI_UNKNOWN = OxBO, 

TON_SUBSCRIBER_AND_NPI_UNKNOWN = OxCO, 

TON_UNKNOWN_AND_NPI_TELE PHONE = 0x81, 

TON_INTERNATIONAL_AND_NPI_TELEPHONE = 0x91, 

TON_NATIONAL_AND_NPI_TELEPHONE = OxAl , 

TON_NETWORK_AND_NPI_TELE PHONE = OxBl, 

TON SUBSCRIBER AND NPI TELEPHONE = OxCl, 



TON_UNKNO WN_AND_N P I _D ATA 
TON_INTERNAT I ONAL_AND_NP I_DATA 
TON_NAT I ONAL_AND_NP I_DATA 
TON_NETWORK_AND_NP I_DATA 
TON SUBSCRIBER AND NPI DATA 



0x83, 
0x93, 
0xA3, 
0xB3, 
0xC3, 



TON_UNKNOWN_AND_NPI_TELEX 
TON_INTERNATIONAL_AND_NPI_TELEX 
TON_NAT I ONAL_AND_NP I_TELEX 
TON_NETWORK_AND_NPI_TELEX 
TON SUBSCRIBER AND NPI TELEX 



0x84, 
0x94, 
OxA4, 
OxB4, 
OxC4, 



TON_UNKNOWN_AND_NPI_NATIONAL = 0x8 8, 

TON_INTERNATIONAL_AND_NPI_NATIONAL = 0x98, 

TON_NATIONAL_AND_NPI_NATIONAL = 0xA8 , 

TON_NETWORK_AND_NPI_NATIONAL = 0xB8 , 

TON_SUBSCRIBER_AND_NPI_NATIONAL = 0xC8 , 

TON_UNKNOWN_AND_NPI_PRIVATE = 0x8 9, 

TON_INTERNATIONAL_AND_NPI_PRIVATE = 0x99, 

TON_NATIONAL_AND_NPI_PRIVATE = 0xA9 , 

TON_NETWORK_AND_NPI_PRIVATE = 0xB9, 

TON_SUBSCRIBER_AND_NPI_PRIVATE = 0xC9, 

TON_UNKNOWN_AND_NPI_ERMES = 0x8 A, 

TON_INTERNATIONAL_AND_NPI_ERMES = 0x9A, 
TON_NATIONAL_AND_NPI_ERMES = OxAA, 

TON_NETWORK_AND_NPI_ERMES = OxBA, 

TON_SUBSCRIBER_AND_NPI_ERiy[ES = OxCA 
} CatTypeOfNumberAndNumberingPlanldentif ier; 

5. 1 1 .30 CatSendShortMessageOptions 

typedef enum 

{ 

PACKING_NOT_REQUIRED = 0x0 0, 
PACKING_BY_THE_ME_REQUIRED = 0x01 
} CatSendShortMessageOptions; 

5.1 1 .31 CatSendDataOptions 

typedef enum 

{ 

STORE_DATA_IN_TX_BUFFER = 0x0 0, 
SEND_DATA_IMMEDIATELY = 0x01 
} CatSendDataOptions; 
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5.1 1 .32 CatMEInterfaceTransportLevelType 

typedef struct 
{ 



UDP = 0x01, 

TCP = 0x02 
} TransportProtocolType; 
UINT16 CAT_ME_PortNumber; 
CAT_MEInterfaceTransportLevelType; 



5.11.33 CatBearer 



typedef enum 

{ 

BEARER_SMS 
BEARER_CSD 
BEARER_USSD 
BEARER_GPRS 
} CatBearer; 



0x00, 
0x01, 
0x02, 
0x03 



5. 1 1 .34 CatOpenChannelOptions 

typedef enum 

{ 

ON_DEMAND_LINK_ESTABLISHMENT = 0x00, 
IMMEDIATE_LINK_ESTABLISHMENT = 0x01 
} CatOpenChannelOptions; 

5.11.35 CatAddressType 

typedef struct 
{ 



IPV4 = 0x21, 

IPV6 = 0x97 
} AddressType; 
BYTE AddressLength; 
const void *Address; 
CatAddressType ; 



5.11.36 CatFID 



#define FID_DF_GRAPHICS 0x5F5 
#define FID_DF_TELECOM Ox7F10 
#define FID_EF_ADN 0x6F3A 
#define FID_EF_ARR 0x2F06 
#define FID_EF_BDN 0x6F4D 
#define FID_EF_CCP 0x6F3D 
#define FID_EF_DIR 0x2F00 
#define FID_EF_EXT1 Ox6F4A 
#define FID_EF_EXT2 0x6F4B 
#define FID_EF_EXT3 0x6F4C 
#define FID_EF_EXT4 Ox6F4E 
#define FID_EF_FDN 0x6F3B 
#define FID_EF_ICCID 0x2FE2 
#define FID_EF_IMG Ox4F2 
#define FID_EF_LND Ox6F44 
#define FID_EF_MSISDN 0x6F4 
#define FID_EF_PL 0x2F05 
#define FID_EF_SDN 0x6F4 9 
#define FID_EF_SMS 0x6F3C 
#define FID_EF_SMSP Ox6F42 
#define FID_EF_SMSR Ox6F4 7 
#define FID EF SMSS 0x6F43 
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5.11.37 CatTextFormat 



#define 


TEXT_ 


_FORMAT_ 


_LEFT 


#define 


TEXT_ 


[format_ 


[center 


#define 


TEXT_ 


[format_ 


[right 


#define 


TEXT_ 


[format_ 


[lANGUAGE_DE PENDENT 


#define 


TEXT_ 


_FORMAT_ 


_NORMAL_SIZE 


#def ine 


TEXT_ 


_FORMAT_ 


_LARGE_SIZE 


#def ine 


TEXT 


FORMAT 


SMALL SIZE 


#define 


text' 


'format' 


'bold 


#define 


text] 


[format] 


[italic 


#define 


TEXT_ 


[format_ 


[underlined 


#define 


TEXT 


'format 


'STRIKETHROUGH 



0x00 
0x01 
0x02 
0x03 
0x00 
0x04 
0x08 
0x10 
0x2 
0x4 
0x80 



5.11.38 CatTextForegroundColour 



typedef enum { 






BLACK 


= 


0x00 


DARK GREY 


= 


0x01 


DARK_RED 


= 


0x02 


DARK_YELLOW 


= 


0x03 


DARK_GREEN 


= 


0x04 


DARK_CYAN 


= 


0x05 


DARK_BLUE 


= 


0x06 


DARK_MAGENTA 


= 


0x07 


GREY 


= 


0x08 


WHITE 


= 


0x09 


BRIGHT_RED 


= 


OxOA 


BRIGHT_YELLOW 


= 


OxOB 


BRIGHT_GREEN 


= 


OxOC 


BRIGHT_CYAN 


= 


OxOD 


BRIGHT_BLUE 


= 


OxOE 


BRIGHT_MAGENTA 


= 


OxOF 


} CatTextForegroundColour; 







5.1 1 .39 CatTextBackgroundColour 



typedef enum { 






BLACK 


= 


0x00 


DARK_GREY 


= 


0x10 


DARK_RED 


= 


0x2 


DARK_YELLOW 


= 


0x3 


DARK GREEN 


= 


0x4 


DARK CYAN 


= 


0x50 


DARK_BLUE 


= 


0x60 


DARK_MAGENTA 


= 


0x70 


GREY 


= 


0x80 


WHITE 


= 


0x90 


BRIGHT_RED 


= 


OxAO 


BRIGHT_YELLOW 


= 


OxBO 


BRIGHT GREEN 


= 


OxCO 


BRIGHT CYAN 


= 


OxDO 


BRIGHT_BLUE 


= 


OxEO 


BRIGHT_MAGENTA 


= 


OxFO 


} CatTextBackgroundColour; 
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Annex A (normative): 

Application executable architecture 



Name 


Value 


Meaning 


EM NONE 





No machine 


EM M32 


1 


AT&T WE 321 00 


EM SPARC 


2 


SPARC 


EM 386 


3 


Intel 80386 


EM 68K 


4 


Motorola 68000 


EM 88K 


5 


Motorola 88000 


RESERVED 


6 


Reserved for future use 


EM 860 


7 


Intel 80860 


EM MIPS 


8 


MIPS 1 Architecture 


EM S370 


9 


IBM System/370 Processor 


EM MIPS RS3 LE 


10 


MIPS RS3000 Little-endian 


RESERVED 


11-14 


Reserved for future use 


EM PARISC 


15 


Hewlett-Packard PA-RISC 


RESERVED 


16 


Reserved for future use 


EM VPP500 


17 


Fujitsu VPP500 


EM SPARC32PLUS 


18 


Enhanced instruction set SPARC 


EM 960 


19 


Intel 80960 


EM PPC 


20 


PowerPC 


EM PPC64 


21 


64-bit PowerPC 


RESERVED 


22-35 


Reserved for future use 


EM V800 


36 


NEC V800 


EM FR20 


37 


Fujitsu FR20 


EM RH32 


38 


TRW RH-32 


EM RCE 


39 


Motorola RCE 


EM ARM 


40 


Advanced RISC Machines ARM 


EM ALPHA 


41 


Digital Alpha 


EM SH 


42 


Hitachi SH 


EM SPARCV9 


43 


SPARC Version 9 


EM TRICORE 


44 


Infineon Tricore embedded processor 


EM ARC 


45 


Argonaut RISC Core 


EM H8 300 


46 


Hitachi H8/300 


EM H8 300H 


47 


Hitachi H8/300H 


EM H8S 


48 


Hitachi H8S 


EM H8 500 


49 


Hitachi H8/500 


EM lA 64 


50 


Intel IA-64 processor architecture 


EM MIPS X 


51 


Stanford MIPS-X 


EM COLDFIRE 


52 


Motorola ColdFire 


EM 68HC12 


53 


Motorola M68HC1 2 


EM MMA 


54 


Fujitsu MMA Multimedia Accelerator 


EM PCP 


55 


Siemens PCP 


EM NCPU 


56 


Sony nCPU embedded RISC processor 


EM NDR1 


57 


Denso NDR1 microprocessor 


EM STARCORE 


58 


Motorola Star*Core processor 


EM ME16 


59 


Toyota ME16 processor 


EM ST100 


60 


STMicroelectronics ST100 processor 


EM TINYJ 


61 


Advanced Logic Corp. TinyJ embedded processor family 


Reserved 


62-65 


Reserved for future use 


EM FX66 


66 


Infineon FX66 microcontroller 


EM ST9PLUS 


67 


STMicroelectronics ST9+ 8/16 bit microcontroller 


EM ST7 


68 


STMicroelectronics ST7 8-bit microcontroller 


EM 68HC16 


69 


Motorola MC68HC16 Microcontroller 


EM 68HC11 


70 


Motorola MC68HC1 1 Microcontroller 


EM 68HC08 


71 


Motorola MC68HC08 Microcontroller 


EM 68HC05 


72 


Motorola MC68HC05 Microcontroller 


EM SVX 


73 


Silicon Graphics SVx 


EM ST19 


74 


STMicroelectronics ST19 8-bit microcontroller 


EM VAX 


75 


Digital VAX 


EM CRIS 


76 


Axis Communications 32-bit embedded processor 
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Name 


Value 


Meaning 


EM JAVELIN 


77 


Infineon Technologies 32-bit embedded processor 


EM FIREPATH 


78 


Element 14 64-bit DSP Processor 


EM ZSP 


79 


LSI Logic 16-bit DSP Processor 


EM MMIX 


80 


Donald Knuth's educational 64-bit processor 


EM HUANY 


81 


Harvard University machine-independent object files 


EM PRISM 


82 


SiTera Prism 


EM MEL 


83 


Multos Executable Language (MEL) byte codes 


EM RTE 


84 


Microsoft Smart Card for Windows Runtime Environment byte codes 
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Annex B (informative): 
Example 

/** 

** Example of Toolkit Application written for the C SIM API 
*/ 

#pragma AID AO 000000090001 

#include <stdlib.h> 
#include "application. h" 
#include "cat.h" 
#include "catlow.h" 

#define DF_GSM Ox7F2 
#define EF_PUCT Ox6F41 

const BYTE SERVER_OPERATION = 0x0 F ; 

const BYTE EXIT_REQUESTED_BY_USER = 0x10; 

static const char menuEntry[] = "Servicel"; 

static const char menuTitle [] = "MyMenu" ; 

static char iteml [] = "ITEMl" 

static char item2 [] = "ITEM2" 

static char itemS [] = "ITEMS" 

static char item4 [] = "ITEM4" 

static char textDText [] = "Hello, world" 

static char textGInput [] = "Your name?"; 

BYTE Itemldentif ier; 

static BYTE * byteptr; 

static void * bufptr; 

static BYTE buffer [10]; 

static BYTE itemid; 

static BYTE result 

static BYTE repeat 

void main (void) 

{ 

switch (CatGetFrameworkEvent ( ) ) 

{ 

case EVENT_APPLICATION_LIFECYCLE_INSTALL : 
// Define the application Menu Entry and register to the EVENT_MENU_SELECTION 
CatSetMenuString (1, sizeof (menuEntry) , (const void *) MenuEntry,NULL, , 0) ; 
// register to the EVENT_UNFORMATTED_SMS_PP_ENV 
CatNotifyOnEnvelope (SMS_PP_DOWNLOAD_TAG, 1) ; 
break; 
case EVENT_ENVELOPE_COMMAND : 

{ 

BYTE length; 

switch (CatOpenEnvelope (&length) ) 

{ 

case MENU_SELECTION_TAG: 

// Prepare the Select Item proactive command 

// Append the Menu Title 

CatSelectltem (sizeof (MenuTitle) , 
(const void *) MenuTitle, 
DEFAULT_STYLE_NO_HELP) ; 

// add all the Item 

CatSelectAddltem (sizeof (iteml) 

CatSelectAddltem (sizeof (item2) 

CatSelectAddltem (sizeof (item3) 

CatSelectAddltem (sizeof (item4) 

// ask the CAT Toolkit Framework to send 
//the proactive command and check the result 

if ( !CatEndSelectItem(&ItemId,NULL) ) 

{ 

switch (Itemid) 



(const 


void 


*) iteml 


1) 


(const 


void 


*) item2 


2) 


(const 


void 


*) items 


3) 


(const 


void 


*) item4 


4) 



case 1 
case 2 
case 3 



// DisplayText 



CatDisplayText (DCS_SMS_UNPACKED, 
(const void *) textDText, 



sizeof (textDText) 
NORMAL PRIORITY USER CLEAR, NULL, 0) ; 
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break; 
case 4 : // Ask the user to enter data and display it 
repeat =0 ; 
do 

{ 

if (CatGet Input (DCS_SMS_UNPACKED, 
sizeof (textGInput) , 

(const void *) textGInput, 

UNPACKED_SMS_ALPHABET_NO_HELP , 

DCS_SMS_UNPACKED, 0, NULL, 

0, sizeof (buffer) , NULL, 

(CatDCSValue *)&result, 

&repeat , 

(void * ) buffer) ==EXIT_REQUESTED_BY_USER) 
break; 
// display the entered text 
CatDisplayText ((CatDCSValue ) result, 

repeat, (const void *) buffer, 

NORMAL_PRIORITY_USER_CLEAR, NULL, 0) ; 
} while (repeat) ; 

} 
} 

break; 
case E VENT_UNFORMATTED_SMS_P P_ENV : 
CatOpenEnvelope (&result) ; 

byteptr= (BYTE * ) catGetData ( 1) ; /* go to numberlength */ 
result= (*byteptr) >>1; 
/* calculate numberlength, rounded up */ 
if ( (*byteptr) &1) result++; 
catGetData (result+12) ; /* move to the beginning of the data */ 
// get the offset of the instruction in the TP-UD field 
CatGetData (SERVER_OPERATION) ; 
result=CatGetBYTE() ; 

switch (result) 

{ 

case 0x41 : // Update of a gsm file 

bufptr=CatGetData(3) ; 
// write these data in the Efpuct 
CatSelect (FID_DF_GSM) ; 
CatSelect (FID_EF_PUCT) ; 
CatUpdateBinary (0,3, buf ptr ) ; 
break; 
case 0x36 : // change the MenuTitle for the Selectltem 

bufptr=CatGetData (sizeof (menuTitle) ) ; 

memcpy (buf ptr, memuTitle, sizeof (menuTitle) ) ; 



break; 
default : 
CatExit 
break; 

} 

CatExit ; 
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Annex C (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc 


CR 


Re 

V 


Cat 


Subject/Comment 


Old 


New 


2003-03 


TP-19 


TP-030023 


001 




D 


Editorial Corrrections 


6.0.0 


6.1.0 


2007-06 


- 


- 


- 


- 


- 


Update to Rel-7 version (IVICC) 


6.1.0 


7.0.0 


2009-03 


- 


- 


- 


- 


- 


Update to Rel-8 version (IVICC) 


7.1.0 


8.0.0 
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